Site shape analysis

mkdocs.yml

@@ -12,6 +12,7 @@ nav:
     - Simple Example: notebooks/simple.ipynb
     - Loading a CIF File: notebooks/CIF.ipynb
     - Autogenerated Sites: notebooks/auto.ipynb
+    - Shape analysis: notebooks/shape_analysis.ipynb
     - Pathways: notebooks/paths.ipynb
   - Python API:
     - gemdat: api/gemdat.md

pyproject.toml

@@ -35,7 +35,7 @@ dependencies = [
   'matplotlib >= 3.6.0',
   'MDAnalysis',
   'numpy',
-  'pymatgen >= 2023.8.10',
+  'pymatgen >= 2023.11.10',
   'rich',
   'scikit-image',
   'scipy',

src/gemdat/__init__.py

@@ -1,17 +1,20 @@
 from __future__ import annotations
 
 from .io import load_known_material, read_cif
+from .shape import ShapeAnalyzer
 from .simulation_metrics import SimulationMetrics
 from .sites import SitesData
 from .trajectory import Trajectory
-from .volume import trajectory_to_volume
+from .volume import Volume, trajectory_to_volume
 
 __version__ = '0.9.4'
 __all__ = [
     'read_cif',
     'load_known_material',
+    'ShapeAnalyzer',
     'SimulationMetrics',
     'SitesData',
     'Trajectory',
     'trajectory_to_volume',
+    'Volume',
 ]

src/gemdat/plots/__init__.py

@@ -2,45 +2,42 @@
 from __future__ import annotations
 
 # Matplotlib plots
-from .matplotlib._displacements import displacement_per_site
-from .matplotlib._jumps import (
+from .matplotlib import (
     collective_jumps,
+    displacement_per_site,
+    energy_along_path,
+    frequency_vs_occurence,
     jumps_3d,
     jumps_3d_animation,
-)
-from .matplotlib._paths import (
-    energy_along_path,
     path_on_grid,
+    radial_distribution,
+    shape,
 )
-from .matplotlib._rdf import radial_distribution
-from .matplotlib._vibration import frequency_vs_occurence
 
 # Plotly plots (matplotlib version might be available)
-from .plotly._density import density
-from .plotly._displacements import (
+from .plotly import (
+    density,
     displacement_histogram,
     displacement_per_element,
-)
-from .plotly._jumps import (
     jumps_vs_distance,
     jumps_vs_time,
+    vibrational_amplitudes,
 )
-from .plotly._paths import path_on_landscape
-from .plotly._vibration import vibrational_amplitudes
 
 __all__ = [
+    'collective_jumps',
     'density',
-    'displacement_per_site',
-    'displacement_per_element',
     'displacement_histogram',
+    'displacement_per_element',
+    'displacement_per_site',
     'frequency_vs_occurence',
-    'vibrational_amplitudes',
-    'jumps_vs_distance',
-    'jumps_vs_time',
-    'collective_jumps',
     'jumps_3d',
     'jumps_3d_animation',
+    'jumps_vs_distance',
+    'jumps_vs_time',
     'radial_distribution',
+    'shape',
+    'vibrational_amplitudes',
     'energy_along_path',
     'path_on_grid',
     'path_on_landscape',

src/gemdat/plots/matplotlib/__init__.py

@@ -14,22 +14,30 @@
     jumps_vs_distance,
     jumps_vs_time,
 )
+from ._paths import (
+    energy_along_path,
+    path_on_grid,
+)
 from ._rdf import radial_distribution
+from ._shape import shape
 from ._vibration import (
     frequency_vs_occurence,
     vibrational_amplitudes,
 )
 
 __all__ = [
-    'displacement_per_site',
-    'displacement_per_element',
+    'collective_jumps',
     'displacement_histogram',
+    'displacement_per_element',
+    'displacement_per_site',
+    'energy_along_path',
     'frequency_vs_occurence',
-    'vibrational_amplitudes',
-    'jumps_vs_distance',
-    'jumps_vs_time',
-    'collective_jumps',
     'jumps_3d',
     'jumps_3d_animation',
+    'jumps_vs_distance',
+    'jumps_vs_time',
+    'path_on_grid',
     'radial_distribution',
+    'shape',
+    'vibrational_amplitudes',
 ]

src/gemdat/plots/matplotlib/_shape.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Sequence
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+if TYPE_CHECKING:
+    from gemdat.shape import ShapeData
+
+
+def shape(shape: ShapeData, bins: int | Sequence[float] = 50) -> plt.Figure:
+    """Plot site cluster shapes.
+
+    Parameters
+    ----------
+    shape : ShapeData
+        Shape data to plot
+    bins : int | Sequence[float]
+        Number of bins or sequence of bin edges.
+        See [hist()][matplotlib.pyplot.hist] for more info.
+
+    Returns
+    -------
+    fig : matplotlib.figure.Figure
+        Output figure
+    """
+    x_labels = ('X / Å', 'Y / Å', 'Z / Å')
+    y_labels = ('Y / Å', 'Z / Å', 'X / Å')
+
+    fig, axes = plt.subplots(nrows=2,
+                             ncols=3,
+                             sharex=True,
+                             figsize=(12, 5),
+                             gridspec_kw={'height_ratios': (4, 1)})
+
+    distances_sq = shape.distances()**2
+
+    msd = np.mean(distances_sq)
+    std = np.std(distances_sq)
+    title = f'{shape.name}: MSD = {msd:.3f}$~Å^2$, std = {std:.3f}'
+
+    axes[0, 1].set_title(title)
+
+    for i, (x, y) in enumerate(
+        ((shape.x, shape.y), (shape.y, shape.z), (shape.z, shape.x))):
+        ax0 = axes[0, i]
+        ax1 = axes[1, i]
+
+        ax0.hist2d(x=x, y=y, bins=bins)
+        ax0.set_ylabel(y_labels[i])
+
+        circle = plt.Circle((0, 0), msd, color='r', linestyle='--', fill=False)
+        ax0.add_patch(circle)
+
+        ax0.scatter(x=[0], y=[0], color='r', marker='.')
+        ax0.axis('equal')
+
+        ax1.hist(x=x, bins=bins, density=True)
+        ax1.set_xlabel(x_labels[i])
+        ax1.set_ylabel('density')
+
+    fig.tight_layout()
+
+    return fig

src/gemdat/plots/plotly/__init__.py

@@ -0,0 +1,24 @@
+"""This module contains all the plots that Gemdat can generate with plotly."""
+from __future__ import annotations
+
+from ._density import density
+from ._displacements import (
+    displacement_histogram,
+    displacement_per_element,
+)
+from ._jumps import (
+    jumps_vs_distance,
+    jumps_vs_time,
+)
+from ._paths import path_on_landscape
+from ._vibration import vibrational_amplitudes
+
+__all__ = [
+    'density',
+    'displacement_histogram',
+    'displacement_per_element',
+    'jumps_vs_distance',
+    'jumps_vs_time',
+    'path_on_landscape',
+    'vibrational_amplitudes',
+]