Skip to content

extended

ExtendedPhaseMapping

Pipeline for extended phase mapping on phasefield data.

This class processes a given phasefield by applying optional filters, extracting cycles (from faces and/or boundaries), and categorizing them into critical, noncritical, and wavefront cycles. It provides a structured way to analyze spatiotemporal phase dynamics using topological criteria.

Attributes:

Name Type Description
phasefield PhaseField

The input phasefield mesh.
phasefield_filters list

List of filters to apply to the phasefield.
cycles DataFrame

DataFrame containing all extracted cycles.
critical_cycles DataFrame

Cycles with non-zero topological charge.
noncritical_cycles DataFrame

Cycles with zero topological charge and more nodes than a single face.
wavefront_cycles DataFrame

Cycles corresponding to propagating wavefronts (non-zero wave number, zero topological charge, and equal to the face size).

critical_cycles = pd.DataFrame() instance-attribute

cycles = None instance-attribute

noncritical_cycles = pd.DataFrame() instance-attribute

phasefield = phasefield instance-attribute

phasefield_filters = phasefield_filters or [] instance-attribute

wavefront_cycles = pd.DataFrame() instance-attribute

__init__(phasefield, phasefield_filters=None)

Initialize the ExtendedPhaseMapping pipeline.

Parameters:

Name Type Description Default
phasefield PhaseField

The phasefield mesh to be processed.

 required
phasefield_filters list

List of functions to filter the phasefield.

 None

run(extract_faces=True, extract_boundaries=True)

Execute the ExtendedPhaseMapping pipeline.

Applies filters and extracts cycles from the phasefield.

Parameters:

Name Type Description Default
extract_faces bool

Whether to extract cycles from the faces of the phasefield (Default=True).

 True
extract_boundaries bool

Whether to extract cycles from the boundaries of the phasefield (Default=True).

 True

NaNFilter

Filter out faces in a PhaseField where any vertex has NaN phase values.

apply(phasefield)

Apply NaN filtering to the given PhaseField.

Parameters:

Name Type Description Default
phasefield PhaseField

The PhaseField object to filter.

 required

Returns:

Name Type Description
PhaseField PhaseField

The PhaseField object with updated face masks.

PhaseDiffFilter

Filter out faces in a PhaseField based on phase differences.

Faces where any edge has an absolute modulated phase difference outside the threshold are filtered out.

threshold: float = threshold instance-attribute

__init__(threshold)

Initialize the PhaseDiffFilter with a threshold.

Parameters:

Name Type Description Default
threshold float

Phase difference threshold for filtering faces.

 required

apply(phasefield)

Apply phase difference filtering to the given PhaseField.

Parameters:

Name Type Description Default
phasefield PhaseField

The PhaseField object to filter.

 required

Returns:

Name Type Description
PhaseField PhaseField

The PhaseField object with updated face masks.

PhaseField

Container for phase field data derived from LATs or signals on a mesh.

Attributes:

Name Type Description
points ndarray

3D coordinates of the mesh points.
faces ndarray

connectivity array. Faces must contain padding indicating the number of points in the face. For example, the two faces [10, 11, 12] and [20, 21, 22, 23] will be represented as [3, 10, 11, 12, 4, 20, 21, 22, 23].
phases ndarray

Phase values for each point and time step.
time_axis ndarray

Time points corresponding to the phases.
face_masks ndarray

Boolean mask per face and time step.

edge_ids = self._build_edge_ids() instance-attribute

face_masks = np.full((self.n_faces, phases.shape[1]), True) instance-attribute

faces = faces instance-attribute

phase_diffs = self._build_face_phase_diffs() instance-attribute

phases = phases instance-attribute

points = points instance-attribute

time_axis = np.arange(phases.shape[-1]) if time_axis is None else time_axis instance-attribute

__init__(points, faces, phases, time_axis=None)

Initialize the phase field.

Parameters:

Name Type Description Default
points ndarray

3D coordinates of the mesh points (M, 3).

 required
faces ndarray

connectivity array. Faces must contain padding indicating the number of points in the face. For example, the two faces [10, 11, 12] and [20, 21, 22, 23] will be represented as [3, 10, 11, 12, 4, 20, 21, 22, 23].

 required
phases ndarray

Phase values for each point and time step.

 required
time_axis array

Time points corresponding to the phases.

 None

copy()

Create a copy of the PhaseField object.

from_lats(points, faces, lats, start=None, stop=None, dt=1.0) classmethod

Generate a sawtooth phase map from local activation times (LATs).

Parameters:

Name Type Description Default
points ndarray

3D coordinates of the mesh points (M, 3).

 required
faces ndarray

connectivity array. Faces must contain padding indicating the number of points in the face. For example, the two faces [10, 11, 12] and [20, 21, 22, 23] will be represented as [3, 10, 11, 12, 4, 20, 21, 22, 23].

 required
lats ndarray

Array of LATs (shape: n_points, n_cycles).

 required
start float | None

Start time. Defaults to None.

 None
stop float | None

Stop time. Defaults to None.

 None
dt float

Time step. Defaults to 1.0.

 1.0

Returns:

Name Type Description
PhaseField PhaseField

Constructed phase field object.

from_periodic_lat(points, faces, initial_lats, period, num_of_period=3, start=None, stop=None, dt=1.0) classmethod

Construct a PhaseField by extrapolating a single LAT value periodically.

Parameters:

Name Type Description Default
points ndarray

3D coordinates of the mesh points (M, 3).

 required
faces ndarray

connectivity array. Faces must contain padding indicating the number of points in the face. For example, the two faces [10, 11, 12] and [20, 21, 22, 23] will be represented as [3, 10, 11, 12, 4, 20, 21, 22, 23].

 required
initial_lats ndarray

Array of LATs (shape: n_points,).

 required
period float

LAT repetition period.

 required
num_of_period int

Number of repeated periods. Defaults to 3.

 3
start float | None

Start time. Defaults to None.

 None
stop float | None

Stop time. Defaults to None.

 None
dt float

Time step. Defaults to 1.0.

 1.0

Returns:

Name Type Description
PhaseField PhaseField

Constructed phase field object.

from_signals(points, faces, signals, start=None, stop=None, dt=1.0) classmethod

Generate a Hilbert-transform-based phase map from signals.

Parameters:

Name Type Description Default
points ndarray

3D coordinates of the mesh points (M, 3).

 required
faces ndarray

connectivity array. Faces must contain padding indicating the number of points in the face. For example, the two faces [10, 11, 12] and [20, 21, 22, 23] will be represented as [3, 10, 11, 12, 4, 20, 21, 22, 23].

 required
signals ndarray

Signal matrix (shape: n_points, n_timesteps).

 required
start float | None

Start time. Defaults to None.

 None
stop float | None

Stop time. Defaults to None.

 None
dt float

Time step. Defaults to 1.0.

 1.0

Returns:

Name Type Description
PhaseField PhaseField

Constructed phase field object.

orientate()

Reorder faces to insure consistent orientation across polygon neighbors.