API Reference

class crispy.FragmentDetector(source: str | List[str], trash_treshold: int = 10)[source]

This class loads AGDD files from a directory or list of file paths, and provides methods to detect, visualize, and analyze fragments.

Parameters:

  • source (str | list[str]) – Path to a directory of AGDD files or a list of file paths.

  • trash_treshold (int, optional) – Minimum number of points to consider a fragment.

Raises:

ValueError – If source is not a string or a list of paths.

build_fragments() → None[source]

Detects fragments from the loaded AGDD files and stores them internally.

get_fragments_by_ID(ID: int) → List[Fragment][source]

Get all fragments that have the specified ID across all iterations.

Parameters:

ID (int) – Fragment ID.

Returns:

List of fragments with the given ID.

Return type:

List[Fragment]

get_fragments_by_iteration(iteration: int) → List[Fragment][source]

Return fragments for a specific iteration.

Parameters:

iteration (int) – Iteration index (must be >= 0).

Returns:

List of fragments for the given iteration.

Return type:

List[Fragment]

Raises:
save() → None[source]

Save all fragment data to text files in a ‘txt’ subfolder.

Raises:

ValueError – If no fragments have been built.

plot2D(iteration: int, show_trash: bool = False, show_bonds: bool = False, auto_close: bool = False, dot_size: int = 4, rigid_lim: bool = True, border_coef: float = 1.5, save: bool = True, save_format: str = 'png') → None[source]

Plot a 2D scatter plot of fragment nodes for a given iteration.

Parameters:

  • iteration (int) – Iteration index to plot.

  • show_trash (bool) – Whether to show trash fragments (ID = -1).

  • show_bonds (bool) – Whether to show bonds between nodes.

  • auto_close (bool) – Whether to automatically close the plot window.

  • dot_size (int) – Size of the dots for each node.

  • rigid_lim (bool) – Whether to keep the axis limits fixed after first plot.

  • border_coef (float) – Expansion factor for plot borders.

  • save (bool) – Whether to save the plot as an image.

  • save_format (str) – File format to save image (e.g., “png”, “pdf”).

Raises:

ValueError – If no fragments were built before plotting.

stackplot(xgrid: bool = True, interline: bool = True, auto_close: bool = False, save: bool = True, save_format: str = 'png') → None[source]

Plot a stack graph of fragment repartition over all iterations.

Parameters:

  • xgrid (bool) – Wether to show vertical line marking iterations.

  • interline (bool) – Whether to show line between fragments repartition.

  • auto_close (bool) – Whether to automatically close the plot window.

  • save (bool) – Whether to save the plot as an image.

  • save_format (str) – File format to save image (e.g., “png”, “pdf”).

Raises:

ValueError – If no fragments were built before plotting.

graphplot(auto_close: bool = False, save: bool = True, save_format: str = 'png') → None[source]

Plot a network graph of fragments.

Parameters:

  • auto_close (bool) – Whether to automatically close the plot window.

  • save (bool) – Whether to save the plot as an image.

  • save_format (str) – File format to save image (e.g., “png”, “pdf”).

Raises:

ValueError – If no fragments were built before plotting.

viewer3D() → None[source]

Launch a 3D viewer to display detected fragments.

Raises:

ValueError – If no fragments have been built.

property directory: str

Work directory from which AGDD files are loaded.

Type:

str

property trash_treshold: int

Minimum number of points for a valid fragment.

Type:

int

property agdd_files: List[str]

List of AGDD file paths.

Type:

List[str]

property fragments: List[List[Fragment]]

All detected fragments by iteration.

Type:

List[List[Fragment]]

property iterations_nb: int

Number of AGDD files processed.

Type:

int

class crispy.Fragment(ID: int, nodeIDs: list, nodes: list, bondIDs: list, bonds: list, iteration: int, parentIDs: list, area: float)[source]

Represents a fragment detected in the simulation.

Parameters:

  • ID (int) – Unique identifier for the fragment.

  • nodeIDs (np.ndarray[int]) – Indices of the nodes that belong to this fragment.

  • nodes (np.ndarray[float]) – Node data (e.g., coordinates and radii).

  • bondIDs (np.ndarray[int]) – Indices of the bonds associated with this fragment.

  • bonds (np.ndarray[int]) – Bond data (e.g., node pairs forming bonds).

  • iteration (int) – Iteration number when this fragment was detected.

  • parentIDs (List[int]) – List of fragment IDs from the previous iteration that contributed to this one.

  • area (float) – Percentage of the total area covered by this fragment.

classmethod detect_from_agdd(detector: FragmentDetector, agdd_file: str, iteration: int, trash_treshold: int) → List[Fragment][source]

Detects fragments from a given AGDD file.

Parameters:

  • detector (FragmentDetector) – The main detector instance containing fragment and configuration data.

  • agdd_file (str) – Path to the AGDD file to process.

  • iteration (int) – Index of the current iteration (frame).

  • trash_treshold (int) – Minimum number of points required to consider a group as a valid fragment.

Returns:

A list of detected Fragment instances for the given iteration.

Return type:

List[Fragment]

property ID: int

Unique identifier of the fragment.

Type:

int

property nodeIDs: ndarray[int]

Indices of the nodes that belong to the fragment.

Type:

np.ndarray[int]

property nodes: ndarray[float]

Array containing the coordinates and radii of the fragment’s nodes.

Type:

np.ndarray[float]

property bondIDs: ndarray[int]

Indices of the bonds associated with the fragment.

Type:

np.ndarray[int]

property bonds: ndarray[int]

Array of node connections (bonds) within the fragment.

Type:

np.ndarray[int]

property iteration: int

Iteration number at which the fragment is detected.

Type:

int

property parentIDs: List[int]

IDs of parent fragments from the previous iteration.

Type:

List[int]

property area: float

Percentage of the total area occupied by the fragment.

Type:

float