Visualization

polymcsim.visualization

Visualization utilities for PolyMCsim polymer graphs.

create_analysis_dashboard(graph, metadata, figsize=(16, 12), title=None, save_path=None)

Create a comprehensive dashboard with multiple polymer analysis plots.

Parameters:

Name	Type	Description	Default
graph	Graph	The NetworkX Graph to analyze.	required
metadata	Dict[str, any]	Simulation metadata.	required
figsize	Tuple[int, int]	Figure size (width, height) in inches.	(16, 12)
title	Optional[str]	Optional title for the dashboard.	None
save_path	Optional[Union[str, Path]]	If provided, saves the figure to this path.	None

Returns:

Type	Description
Figure	Matplotlib Figure object with analysis dashboard.

export_polymer_data(graph, metadata, output_dir, prefix='polymer_analysis')

Export polymer analysis data to CSV files for external analysis.

Parameters:

Name	Type	Description	Default
graph	Graph	The NetworkX Graph to analyze.	required
metadata	Dict[str, any]	Simulation metadata.	required
output_dir	Union[str, Path]	Directory to save the CSV files.	required
prefix	str	Prefix for the output filenames.	'polymer_analysis'

Returns:

Type	Description
Dict[str, Path]	Dictionary mapping data type to file path.

plot_branching_analysis(graph, figsize=(10, 6), title=None, save_path=None)

Analyze and visualize the degree of branching in the polymer.

Parameters:

Name	Type	Description	Default
graph	Graph	The NetworkX Graph to analyze.	required
figsize	Tuple[int, int]	Figure size (width, height) in inches.	(10, 6)
title	Optional[str]	Optional title for the plot.	None
save_path	Optional[Union[str, Path]]	If provided, saves the figure to this path.	None

Returns:

Type	Description
Figure	Matplotlib Figure object with branching analysis.

plot_chain_length_distribution(graph, figsize=(8, 5), title=None, save_path=None)

Plot the distribution of chain lengths in the polymer.

Parameters:

Name	Type	Description	Default
graph	Graph	The NetworkX Graph to analyze.	required
figsize	Tuple[int, int]	Figure size (width, height) in inches.	(8, 5)
title	Optional[str]	Optional title for the plot.	None
save_path	Optional[Union[str, Path]]	If provided, saves the figure to this path.	None

Returns:

Type	Description
Figure	Matplotlib Figure object.

Raises:

Type	Description
TypeError	If input is not a NetworkX Graph object.

plot_conversion_analysis(metadata, edge_data=None, figsize=(12, 8), title=None, save_path=None)

Plot conversion and reaction kinetics analysis.

Parameters:

Name	Type	Description	Default
metadata	Dict[str, any]	Simulation metadata containing conversion and timing info.	required
edge_data	Optional[List[Tuple[int, int, float]]]	Optional list of (node1, node2, time) tuples for kinetic analysis.	None
figsize	Tuple[int, int]	Figure size (width, height) in inches.	(12, 8)
title	Optional[str]	Optional title for the plot.	None
save_path	Optional[Union[str, Path]]	If provided, saves the figure to this path.	None

Returns:

Type	Description
Figure	Matplotlib Figure object with conversion analysis.

plot_molecular_weight_distribution(graph, figsize=(10, 6), bins=50, log_scale=False, show_pdi=True, title=None, save_path=None)

Plot the molecular weight distribution (MWD) of the polymer.

This is more informative than chain length distribution as it accounts for the actual molar masses of different monomer types.

Parameters:

Name	Type	Description	Default
graph	Graph	The NetworkX Graph to analyze.	required
figsize	Tuple[int, int]	Figure size (width, height) in inches.	(10, 6)
bins	Union[int, str, ndarray]	Number of bins or bin specification for histogram.	50
log_scale	bool	Whether to use log scale for x-axis (useful for broad distributions).	False
show_pdi	bool	Whether to calculate and display PDI on the plot.	True
title	Optional[str]	Optional title for the plot.	None
save_path	Optional[Union[str, Path]]	If provided, saves the figure to this path.	None

Returns:

Type	Description
Figure	Matplotlib Figure object with MWD plot.

visualize_polymer(graph, figsize=(12, 8), layout=None, node_size_factor=1.0, node_color_by='monomer_type', node_outline_color='black', with_labels=False, title=None, seed=None, component_index=None, save_path=None)

Visualize a polymer graph with customizable styling.

Parameters:

Name	Type	Description	Default
graph	Graph	The NetworkX Graph to visualize.	required
figsize	Tuple[int, int]	Figure size (width, height) in inches.	(12, 8)
layout	Optional[str]	Graph layout algorithm ('spring', 'kamada_kawai', 'circular').	None
node_size_factor	float	Factor to scale node sizes relative to edge lengths.	1.0
node_color_by	str	Node attribute to use for coloring ('monomer_type' or None).	'monomer_type'
node_outline_color	str	Color of the node outline/border.	'black'
with_labels	bool	Whether to show node labels with monomer type.	False
title	Optional[str]	Optional title for the plot.	None
seed	Optional[int]	Random seed for layout algorithms.	None
component_index	Optional[Union[int, str]]	Which component to plot. Can be: - None: Plot all components. - int: Plot the nth largest component (0 = largest). - 'random': Plot a random component from chains with >1 monomer.	None
save_path	Optional[Union[str, Path]]	If provided, saves the figure to this path.	None

Returns:

Type	Description
Figure	Matplotlib Figure object.

Raises:

Type	Description
TypeError	If input is not a NetworkX Graph object.
ValueError	If layout algorithm is unknown or component index is out of range.