Refactor: Refactor simulation examples

Author: CSSFrancis

doc/conf.py

@@ -175,3 +175,5 @@ def linkcode_resolve(domain, info):
     "ignore_pattern": "_sgskip.py",  # pattern to define which will not be executed
     "reference_url": {"diffsims": None},
 }
+
+autosummary_generate = True

doc/index.rst

@@ -14,32 +14,6 @@ diffsims is an open-source Python library for simulating diffraction.
     changelog.rst
     Examples <examples/index>
 
-
-Installation
-============
-
-diffsims can be installed with `pip <https://pypi.org/project/diffsims>`__ or
-`conda <https://anaconda.org/conda-forge/diffsims>`__:
-
-.. tab-set::
-
-    .. tab-item:: pip
-
-        .. code-block:: bash
-
-            pip install diffsims
-
-    .. tab-item:: conda
-
-        .. code-block:: bash
-
-            conda install diffsims -c conda-forge
-
-Further details are available in the :doc:`installation guide <user/installation>`.
-
-Learning resources
-==================
-
 .. See: https://sphinx-design.readthedocs.io/en/furo-theme/grids.html
 .. grid:: 2
     :gutter: 2
@@ -68,6 +42,46 @@ Learning resources
         :octicon:`people;2em;sd-text-info` Contributing
         ^^^
 
+        Guide for contributing to diffsims.
+
+    .. grid-item-card::
+        :link: dev/examples
+        :link-type: doc
+
+        :octicon:`zap;2em;sd-text-info` Examples
+        ^^^
+
+        Gallery of short examples illustrating simple tasks that can be performed with diffsims.
+
+
+
+Installation
+============
+
+diffsims can be installed with `pip <https://pypi.org/project/diffsims>`__ or
+`conda <https://anaconda.org/conda-forge/diffsims>`__:
+
+.. tab-set::
+
+    .. tab-item:: pip
+
+        .. code-block:: bash
+
+            pip install diffsims
+
+    .. tab-item:: conda
+
+        .. code-block:: bash
+
+            conda install diffsims -c conda-forge
+
+Further details are available in the :doc:`installation guide <user/installation>`.
+
+Learning resources
+==================
+
+
+
         diffsims is a community project maintained for and by its users. There are many
         ways you can help!
 

doc/user/index.rst

@@ -11,6 +11,13 @@ use diffsims.
 
     installation.rst
 
+.. toctree::
+    :caption: Usage
+    :maxdepth: 2
+    https://github.com/pyxem/diffsims-demos
+    ../examples/index.rst
+
+    installation.rst
 .. toctree::
     :caption: Resources
 

examples/creating_a_simulation_library/README.rst

@@ -1,6 +1,4 @@
-.. _examples-index:
+Creating a Simulation Library
+=============================
 
-Simulation Library
-==================
-
-These examples show specific workflows for creating a library of simulations
+These examples show specific workflows for creating a library of simulations.

examples/creating_a_simulation_library/migration_guide.py

@@ -11,21 +11,22 @@
 """
 
 import numpy as np
-import diffpy
 import matplotlib.pyplot as plt
+from diffpy.structure import Atom, Lattice, Structure
+
 from diffsims.libraries.structure_library import StructureLibrary
 from diffsims.generators.diffraction_generator import DiffractionGenerator
 from diffsims.generators.library_generator import DiffractionLibraryGenerator
 
 
-latt = diffpy.structure.lattice.Lattice(4, 4, 4, 90, 90, 90)
+latt = Lattice(4, 4, 4, 90, 90, 90)
 atoms = [
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
+    Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
+    Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
 ]
-structure_matrix = diffpy.structure.Structure(atoms=atoms, lattice=latt)
+structure_matrix = Structure(atoms=atoms, lattice=latt)
 euler_angles = np.array([[0, 0, 0], [10.0, 0.0, 0.0]])
 struct_library = StructureLibrary(["Al"], [structure_matrix], [euler_angles])
 diff_gen = DiffractionGenerator(accelerating_voltage=200)
@@ -43,19 +44,18 @@
 # New
 # ---
 
-import diffpy
 from orix.crystal_map import Phase
 from orix.quaternion import Rotation
 from diffsims.generators.simulation_generator import SimulationGenerator
 
-latt = diffpy.structure.lattice.Lattice(4, 4, 4, 90, 90, 90)
+latt = Lattice(4, 4, 4, 90, 90, 90)
 atoms = [
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
-    diffpy.structure.atom.Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
+    Atom(atype="Al", xyz=[0.0, 0.0, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.5, 0.0], lattice=latt),
+    Atom(atype="Al", xyz=[0.5, 0.0, 0.5], lattice=latt),
+    Atom(atype="Al", xyz=[0.0, 0.5, 0.5], lattice=latt),
 ]
-structure_matrix = diffpy.structure.Structure(atoms=atoms, lattice=latt)
+structure_matrix = Structure(atoms=atoms, lattice=latt)
 p = Phase("Al", point_group="m-3m", structure=structure_matrix)
 gen = SimulationGenerator(accelerating_voltage=200)
 rot = Rotation.from_euler([[0, 0, 0], [10.0, 0.0, 0.0]], degrees=True)
@@ -78,5 +78,7 @@
     axs[i, 1].set_xlim(-1.5, 1.5)
     axs[i, 1].set_ylim(-1.5, 1.5)
 
-axs[0, 0].set_title("Old")
-axs[0, 1].set_title("New")
+_ = axs[0, 0].set_title("Old")
+_ = axs[0, 1].set_title("New")
+
+# %%

examples/creating_a_simulation_library/simulating_diffraction_patterns.py

@@ -1,7 +1,16 @@
 """
-=====================================================
-Simulating One Diffraction Pattern for a Single Phase
-=====================================================
+==============================================
+Simple Diffraction Pattern Simulation Examples
+==============================================
+
+This example demonstrates how to simulate diffraction patterns using the
+:class:`diffsims.generators.simulation_generator.SimulationGenerator` class. A
+single diffraction pattern can be simulated for a single phase or multiple
+diffraction patterns can be simulated for a single/multiple phases given
+a rotation.
+
+One Pattern for One Phase
+--------------------------
 """
 
 from orix.crystal_map import Phase
@@ -31,35 +40,35 @@
 )  # 45 degree rotation around x-axis
 sim = gen.calculate_diffraction2d(phase=p, rotation=rot)
 
-sim.plot(show_labels=True)  # plot the first (and only) diffraction pattern
+_ = sim.plot(show_labels=True)  # plot the first (and only) diffraction pattern
 
 # %%
 
 sim.coordinates  # coordinates of the first (and only) diffraction pattern
 
 # %%
-# ===========================================================
-# Simulating Multiple Rotations for a Single Phase
-# ===========================================================
+# Simulating Multiple Patterns for a Single Phase
+# -----------------------------------------------
 
 rot = Rotation.from_axes_angles(
     [1, 0, 0], (0, 15, 30, 45, 60, 75, 90), degrees=True
 )  # 45 degree rotation around x-axis
 sim = gen.calculate_diffraction2d(phase=p, rotation=rot)
 
-sim.plot(show_labels=True)  # plot the first diffraction pattern
+_ = sim.plot(show_labels=True)  # plot the first diffraction pattern
 
 # %%
 
-sim.irot[3].plot(show_labels=True)  # plot the fourth(45 degrees) diffraction pattern
+_ = sim.irot[3].plot(
+    show_labels=True
+)  # plot the fourth(45 degrees) diffraction pattern
 # %%
 
 sim.coordinates  # coordinates of all the diffraction patterns
 
 # %%
-# ============================================================
-# Simulating Multiple Rotations for Multiple Phases
-# ============================================================
+# Simulating Multiple Patterns for Multiple Phases
+# ------------------------------------------------
 
 p2 = p.deepcopy()  # copy the phase
 
@@ -70,24 +79,23 @@
 )  # 45 degree rotation around x-axis
 sim = gen.calculate_diffraction2d(phase=[p, p2], rotation=[rot, rot])
 
-sim.plot(
+_ = sim.plot(
     include_direct_beam=True, show_labels=True, min_label_intensity=0.1
 )  # plot the first diffraction pattern
 
 # %%
 
-sim.iphase["al_2"].irot[3].plot(
-    show_labels=True, min_label_intensity=0.1
+_ = (
+    sim.iphase["al_2"].irot[3].plot(show_labels=True, min_label_intensity=0.1)
 )  # plot the fourth(45 degrees) diffraction pattern
 
 # %%
-# ===================================
-# Plotting a Real Diffraction Pattern
-# ===================================
+# Plotting a Pixelated Diffraction Pattern
+# ----------------------------------------
 dp = sim.get_diffraction_pattern(
     shape=(512, 512),
     calibration=0.01,
 )
 plt.figure()
-plt.imshow(dp)
+_ = plt.imshow(dp)
 # %%