From c34e4b69506bf0073762500b54f5aac0db6c3459 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Wed, 17 Apr 2024 09:53:12 -0500 Subject: [PATCH 01/13] Examples: Add examples for simulating diffraction libraries. --- .../migration_guide.py | 80 ++++++++++++++++ .../simulating_diffraction_patterns.py | 94 +++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 examples/creating_a_simulation_library/migration_guide.py create mode 100644 examples/creating_a_simulation_library/simulating_diffraction_patterns.py diff --git a/examples/creating_a_simulation_library/migration_guide.py b/examples/creating_a_simulation_library/migration_guide.py new file mode 100644 index 00000000..bd8ccdd6 --- /dev/null +++ b/examples/creating_a_simulation_library/migration_guide.py @@ -0,0 +1,80 @@ +""" +0.5.x --> 0.6.x Migration Guide +=============================== +This is a migration guide for version 0.5.x to 0.6.x. This guide helps to show the changes +that were made to the API and how to update your code to use the new API. + +Here you can see how to make an equivalent to a diffraction library +""" + +# Old + +import numpy as np +import diffpy +import matplotlib.pyplot as plt +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) +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), +] +structure_matrix = diffpy.structure.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) +lib_gen = DiffractionLibraryGenerator(diff_gen) +diff_lib = lib_gen.get_diffraction_library( + struct_library, + calibration=0.0262, + reciprocal_radius=1.6768, + half_shape=64, + with_direct_beam=True, + max_excitation_error=0.02, +) + + +# 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) +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), +] +structure_matrix = diffpy.structure.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) +sim = gen.calculate_ed_data( + phase=p, + rotation=rot, + reciprocal_radius=1.6768, + max_excitation_error=0.02, + with_direct_beam=True, +) + +fig, axs = plt.subplots(2, 2, figsize=(10, 10)) +for i in range(2): + diff_lib["Al"]["simulations"][i].plot( + size_factor=15, show_labels=True, ax=axs[i, 0] + ) + sim.irot[i].plot(ax=axs[i, 1], size_factor=15, show_labels=True) + axs[i, 0].set_xlim(-1.5, 1.5) + axs[i, 0].set_ylim(-1.5, 1.5) + 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") diff --git a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py new file mode 100644 index 00000000..0d537a13 --- /dev/null +++ b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py @@ -0,0 +1,94 @@ +""" +===================================================== + Simulating One Diffraction Pattern for a Single Phase +===================================================== +""" + +from orix.crystal_map import Phase +from orix.quaternion import Rotation +from diffpy.structure import Atom, Lattice, Structure +import matplotlib.pyplot as plt + +from diffsims.generators.simulation_generator import SimulationGenerator + +a = 5.431 +latt = Lattice(a, a, a, 90, 90, 90) +atom_list = [] +for coords in [[0, 0, 0], [0.5, 0, 0.5], [0, 0.5, 0.5], [0.5, 0.5, 0]]: + x, y, z = coords[0], coords[1], coords[2] + atom_list.append(Atom(atype="Si", xyz=[x, y, z], lattice=latt)) # Motif part A + atom_list.append( + Atom(atype="Si", xyz=[x + 0.25, y + 0.25, z + 0.25], lattice=latt) + ) # Motif part B +struct = Structure(atoms=atom_list, lattice=latt) +p = Phase(structure=struct, space_group=227) + +gen = SimulationGenerator( + accelerating_voltage=200, +) +rot = Rotation.from_axes_angles( + [1, 0, 0], 45, degrees=True +) # 45 degree rotation around x-axis +sim = gen.calculate_ed_data(phase=p, rotation=rot) + +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 +# =========================================================== + +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_ed_data(phase=p, rotation=rot) + +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.coordinates # coordinates of all the diffraction patterns + +# ============================================================ +# Simulating Multiple Rotations for Multiple Phases +# ============================================================ + +p2 = p.deepcopy() # copy the phase + +p2.name = "al_2" + +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_ed_data(phase=[p, p2], rotation=[rot, rot]) + +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 +) # plot the fourth(45 degrees) diffraction pattern + + +# =================================== +# Plotting a Real Diffraction Pattern +# =================================== +dp = sim.get_diffraction_pattern( + shape=(512, 512), + calibration=0.01, +) +plt.figure() +plt.imshow(dp) +# %% From 1fab94bb85fe2293f0e01d43dcd874469fde0b9a Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Wed, 17 Apr 2024 10:01:39 -0500 Subject: [PATCH 02/13] Examples: Clean up example scripts for building documentation --- doc/conf.py | 13 +++++++++++++ doc/index.rst | 2 ++ examples/README.rst | 6 ++++++ examples/creating_a_simulation_library/README.rst | 6 ++++++ .../simulating_diffraction_patterns.py | 2 +- 5 files changed, 28 insertions(+), 1 deletion(-) create mode 100644 examples/README.rst create mode 100644 examples/creating_a_simulation_library/README.rst diff --git a/doc/conf.py b/doc/conf.py index 0179cf6d..dd85b0cd 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -46,6 +46,7 @@ "sphinx.ext.mathjax", "sphinx.ext.napoleon", "sphinx_design", + "sphinx_gallery.gen_gallery", ] # Create links to references within diffsims' documentation to these packages @@ -162,3 +163,15 @@ def linkcode_resolve(domain, info): autodoc_default_options = { "show-inheritance": True, } + +# -- Sphinx-Gallery--------------- +# https://sphinx-gallery.github.io +sphinx_gallery_conf = { + "backreferences_dir": "reference/generated", + "doc_module": ("diffsims",), + "examples_dirs": "../examples", # path to your example scripts + "gallery_dirs": "examples", # path to where to save gallery generated output + "filename_pattern": "^((?!sgskip).)*$", # pattern to define which will be executed + "ignore_pattern": "_sgskip.py", # pattern to define which will not be executed + "reference_url": {"diffsims": None}, +} diff --git a/doc/index.rst b/doc/index.rst index 26de4faa..8b7e2fae 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,6 +12,8 @@ diffsims is an open-source Python library for simulating diffraction. reference/index.rst dev/index.rst changelog.rst + Examples + Installation ============ diff --git a/examples/README.rst b/examples/README.rst new file mode 100644 index 00000000..baa7152e --- /dev/null +++ b/examples/README.rst @@ -0,0 +1,6 @@ +.. _examples-index: + +Gallery of Examples +=================== + +Below is a gallery of examples for different operations in diffsims. diff --git a/examples/creating_a_simulation_library/README.rst b/examples/creating_a_simulation_library/README.rst new file mode 100644 index 00000000..734491a4 --- /dev/null +++ b/examples/creating_a_simulation_library/README.rst @@ -0,0 +1,6 @@ +.. _examples-index: + +Simulation Library +================== + +These examples show specific workflows for creating a library of simulations diff --git a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py index 0d537a13..ac5af703 100644 --- a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py +++ b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py @@ -1,6 +1,6 @@ """ ===================================================== - Simulating One Diffraction Pattern for a Single Phase +Simulating One Diffraction Pattern for a Single Phase ===================================================== """ From cf66851d86567e350205b01456c724c9879725a7 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Wed, 17 Apr 2024 13:11:28 -0500 Subject: [PATCH 03/13] Refactor: calculate_ed_data--> calculate_diffraction2d in examples --- examples/creating_a_simulation_library/migration_guide.py | 2 +- .../simulating_diffraction_patterns.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/creating_a_simulation_library/migration_guide.py b/examples/creating_a_simulation_library/migration_guide.py index bd8ccdd6..19c339d1 100644 --- a/examples/creating_a_simulation_library/migration_guide.py +++ b/examples/creating_a_simulation_library/migration_guide.py @@ -57,7 +57,7 @@ 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) -sim = gen.calculate_ed_data( +sim = gen.calculate_diffraction2d( phase=p, rotation=rot, reciprocal_radius=1.6768, diff --git a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py index ac5af703..5fbd5bc5 100644 --- a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py +++ b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py @@ -29,7 +29,7 @@ rot = Rotation.from_axes_angles( [1, 0, 0], 45, degrees=True ) # 45 degree rotation around x-axis -sim = gen.calculate_ed_data(phase=p, rotation=rot) +sim = gen.calculate_diffraction2d(phase=p, rotation=rot) sim.plot(show_labels=True) # plot the first (and only) diffraction pattern @@ -47,7 +47,7 @@ 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_ed_data(phase=p, rotation=rot) +sim = gen.calculate_diffraction2d(phase=p, rotation=rot) sim.plot(show_labels=True) # plot the first diffraction pattern @@ -69,7 +69,7 @@ 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_ed_data(phase=[p, p2], rotation=[rot, rot]) +sim = gen.calculate_diffraction2d(phase=[p, p2], rotation=[rot, rot]) sim.plot( include_direct_beam=True, show_labels=True, min_label_intensity=0.1 From fec7955a29979d9d649b59c4f9babc90dd78a2e5 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Sun, 21 Apr 2024 09:57:13 -0500 Subject: [PATCH 04/13] Add sphinx gallery to doc requirements --- setup.py | 1 + 1 file changed, 1 insertion(+) diff --git a/setup.py b/setup.py index 1ba7c559..b008f375 100644 --- a/setup.py +++ b/setup.py @@ -30,6 +30,7 @@ "pydata-sphinx-theme", "sphinx >= 3.0.2", "sphinx-design", + "sphinx_gallery", ], "tests": [ "coverage >= 5.0", From 4117bb5b631ac03427550cff3d2af4f0efa7aa13 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Thu, 9 May 2024 11:10:20 -0500 Subject: [PATCH 05/13] Refactor: Add examples to MANIFEST.in --- MANIFEST.in | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/MANIFEST.in b/MANIFEST.in index 2153cf7e..ffbdbf7b 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -12,4 +12,5 @@ include setup.cfg include setup.py include diffsims/tests/**/*.npy -recursive-include doc Makefile make.bat *.rst *.py *.png \ No newline at end of file +recursive-include doc Makefile make.bat *.rst *.py *.png +recursive-include examples *.py *.rst \ No newline at end of file From 357bdafb9d9de89bab0c7c7e10d1ac8570174cfb Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Thu, 9 May 2024 11:26:00 -0500 Subject: [PATCH 06/13] Refactor: Fix formatting --- examples/creating_a_simulation_library/migration_guide.py | 8 +++++--- .../simulating_diffraction_patterns.py | 5 ++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/examples/creating_a_simulation_library/migration_guide.py b/examples/creating_a_simulation_library/migration_guide.py index 19c339d1..07c21810 100644 --- a/examples/creating_a_simulation_library/migration_guide.py +++ b/examples/creating_a_simulation_library/migration_guide.py @@ -5,9 +5,10 @@ that were made to the API and how to update your code to use the new API. Here you can see how to make an equivalent to a diffraction library -""" -# Old +Old +--- +""" import numpy as np import diffpy @@ -38,8 +39,9 @@ max_excitation_error=0.02, ) - +# %% # New +# --- import diffpy from orix.crystal_map import Phase diff --git a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py index 5fbd5bc5..8142706b 100644 --- a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py +++ b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py @@ -38,8 +38,6 @@ sim.coordinates # coordinates of the first (and only) diffraction pattern # %% - - # =========================================================== # Simulating Multiple Rotations for a Single Phase # =========================================================== @@ -58,6 +56,7 @@ sim.coordinates # coordinates of all the diffraction patterns +# %% # ============================================================ # Simulating Multiple Rotations for Multiple Phases # ============================================================ @@ -81,7 +80,7 @@ show_labels=True, min_label_intensity=0.1 ) # plot the fourth(45 degrees) diffraction pattern - +# %% # =================================== # Plotting a Real Diffraction Pattern # =================================== From 777ab630bc2e2375a92006d8dac8a72797ae9a44 Mon Sep 17 00:00:00 2001 From: Carter Francis Date: Thu, 9 May 2024 13:06:24 -0500 Subject: [PATCH 07/13] Refactor: Refactor simulation examples --- doc/conf.py | 2 + doc/index.rst | 66 +++++++++++-------- doc/user/index.rst | 7 ++ .../creating_a_simulation_library/README.rst | 8 +-- .../migration_guide.py | 34 +++++----- .../simulating_diffraction_patterns.py | 46 +++++++------ 6 files changed, 97 insertions(+), 66 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index dd85b0cd..fbbf5be4 100644 --- a/doc/conf.py +++ b/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 diff --git a/doc/index.rst b/doc/index.rst index 8b7e2fae..676e746b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -14,32 +14,6 @@ diffsims is an open-source Python library for simulating diffraction. changelog.rst Examples - -Installation -============ - -diffsims can be installed with `pip `__ or -`conda `__: - -.. 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 `. - -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 `__ or +`conda `__: + +.. 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 `. + +Learning resources +================== + + + diffsims is a community project maintained for and by its users. There are many ways you can help! diff --git a/doc/user/index.rst b/doc/user/index.rst index 3a85f3b2..ec4afb3f 100644 --- a/doc/user/index.rst +++ b/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 diff --git a/examples/creating_a_simulation_library/README.rst b/examples/creating_a_simulation_library/README.rst index 734491a4..7b204c8d 100644 --- a/examples/creating_a_simulation_library/README.rst +++ b/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. diff --git a/examples/creating_a_simulation_library/migration_guide.py b/examples/creating_a_simulation_library/migration_guide.py index 07c21810..613572dd 100644 --- a/examples/creating_a_simulation_library/migration_guide.py +++ b/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") + +# %% diff --git a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py b/examples/creating_a_simulation_library/simulating_diffraction_patterns.py index 8142706b..fafec75f 100644 --- a/examples/creating_a_simulation_library/simulating_diffraction_patterns.py +++ b/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) # %% From 3e301b4d4e81218894824a075ea26bd8c5c8486d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:08:04 +0200 Subject: [PATCH 08/13] Use numpydoc for docs formatting, enable doc nav with arrow keys MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- .gitignore | 2 ++ doc/conf.py | 5 ++--- setup.py | 1 + 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index 643427c0..c4531a41 100644 --- a/.gitignore +++ b/.gitignore @@ -69,7 +69,9 @@ instance/ # Sphinx documentation doc/build/ +doc/examples/ doc/reference/generated/ +doc/sg_execution_times.rst # PyBuilder target/ diff --git a/doc/conf.py b/doc/conf.py index fbbf5be4..106e9f18 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -39,12 +39,12 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "numpydoc", "sphinx.ext.autodoc", "sphinx.ext.autosummary", "sphinx.ext.intersphinx", "sphinx.ext.linkcode", "sphinx.ext.mathjax", - "sphinx.ext.napoleon", "sphinx_design", "sphinx_gallery.gen_gallery", ] @@ -74,7 +74,7 @@ "github_url": "https://github.com/pyxem/diffsims", "header_links_before_dropdown": 6, "logo": {"alt_text": project, "text": project}, - "navigation_with_keys": False, + "navigation_with_keys": True, "show_toc_level": 2, "use_edit_page_button": True, } @@ -175,5 +175,4 @@ def linkcode_resolve(domain, info): "ignore_pattern": "_sgskip.py", # pattern to define which will not be executed "reference_url": {"diffsims": None}, } - autosummary_generate = True diff --git a/setup.py b/setup.py index b008f375..6d835883 100644 --- a/setup.py +++ b/setup.py @@ -27,6 +27,7 @@ # fmt: off extra_feature_requirements = { "doc": [ + "numpydoc", "pydata-sphinx-theme", "sphinx >= 3.0.2", "sphinx-design", From 04de779d99ee8b572a2cc221ba4e0988184f87aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:09:09 +0200 Subject: [PATCH 09/13] Minor fixes to docstring formatting to allow doc build with numpydoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- diffsims/libraries/diffraction_library.py | 2 +- diffsims/libraries/vector_library.py | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/diffsims/libraries/diffraction_library.py b/diffsims/libraries/diffraction_library.py index b0c084e1..ba222156 100644 --- a/diffsims/libraries/diffraction_library.py +++ b/diffsims/libraries/diffraction_library.py @@ -172,7 +172,7 @@ def pickle_library(self, filename): See Also -------- - load_DiffractionLibrary() + load_DiffractionLibrary """ with open(filename, "wb") as handle: diff --git a/diffsims/libraries/vector_library.py b/diffsims/libraries/vector_library.py index f56860cd..35e5a096 100644 --- a/diffsims/libraries/vector_library.py +++ b/diffsims/libraries/vector_library.py @@ -42,7 +42,7 @@ def load_VectorLibrary(filename, safety=False): See Also -------- - VectorLibrary.pickle_library() + VectorLibrary.pickle_library """ if safety: with open(filename, "rb") as handle: @@ -92,7 +92,7 @@ def pickle_library(self, filename): See Also -------- - load_VectorLibrary() + load_VectorLibrary """ with open(filename, "wb") as handle: From 5936535bed3ec5a06dcedd29555dfa3c6563752b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:40:26 +0200 Subject: [PATCH 10/13] Modify "make clean" to remove dirs for build, examples, generated API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/Makefile | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/Makefile b/doc/Makefile index ed880990..b687a144 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -14,6 +14,12 @@ help: .PHONY: help Makefile +clean: + rm -rf $(BUILDDIR) + rm -rf $(SOURCEDIR)/examples + rm -rf $(SOURCEDIR)/reference/generated + rm sg_execution_times.rst + # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile From 8e26b4297bb80160d170b5f8bafaea5e3366f04f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:41:15 +0200 Subject: [PATCH 11/13] Fix header level for Examples README.rst, remove "Gallery of" in title MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- examples/README.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/examples/README.rst b/examples/README.rst index baa7152e..0e9e731a 100644 --- a/examples/README.rst +++ b/examples/README.rst @@ -1,6 +1,7 @@ .. _examples-index: -Gallery of Examples -=================== +======== +Examples +======== Below is a gallery of examples for different operations in diffsims. From 5f7ac679a380b9c56b54685a0af0b77addb354b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:42:19 +0200 Subject: [PATCH 12/13] Fix doc/index examples link and formatting, restructure slightly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/index.rst | 78 ++++++++++++++++++++++------------------------ doc/user/index.rst | 9 ++---- 2 files changed, 40 insertions(+), 47 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 676e746b..a77c1dcb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -12,47 +12,6 @@ diffsims is an open-source Python library for simulating diffraction. reference/index.rst dev/index.rst changelog.rst - Examples - -.. See: https://sphinx-design.readthedocs.io/en/furo-theme/grids.html -.. grid:: 2 - :gutter: 2 - - .. grid-item-card:: - :link: https://github.com/pyxem/diffsims-demos - - :octicon:`book;2em;sd-text-info` Tutorials - ^^^ - - In-depth guides for using diffsims. - - .. grid-item-card:: - :link: reference/index - :link-type: doc - - :octicon:`code;2em;sd-text-info` API reference - ^^^ - - Descriptions of all functions, modules, and objects in diffsims. - - .. grid-item-card:: - :link: dev/index - :link-type: doc - - :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 @@ -77,14 +36,51 @@ diffsims can be installed with `pip `__ or Further details are available in the :doc:`installation guide `. + Learning resources ================== +.. See: https://sphinx-design.readthedocs.io/en/furo-theme/grids.html +.. grid:: 2 + :gutter: 2 + + .. grid-item-card:: + :link: https://github.com/pyxem/diffsims-demos + + :octicon:`book;2em;sd-text-info` Tutorials + ^^^ + + In-depth guides for using diffsims (notebooks hosted on GitHub). + + .. grid-item-card:: + :link: examples/index + :link-type: doc + + :octicon:`zap;2em;sd-text-info` Examples + ^^^ + Short examples illustrating simple tasks that can be performed with diffsims. + + .. grid-item-card:: + :link: reference/index + :link-type: doc + + :octicon:`code;2em;sd-text-info` API reference + ^^^ + + Descriptions of all functions, modules, and objects in diffsims. + + .. grid-item-card:: + :link: dev/index + :link-type: doc + + :octicon:`people;2em;sd-text-info` Contributing + ^^^ diffsims is a community project maintained for and by its users. There are many ways you can help! + Citing diffsims =============== diff --git a/doc/user/index.rst b/doc/user/index.rst index ec4afb3f..f976ea83 100644 --- a/doc/user/index.rst +++ b/doc/user/index.rst @@ -2,9 +2,6 @@ User guide ========== -See the `demos `_ for how to -use diffsims. - .. toctree:: :caption: Getting started :maxdepth: 1 @@ -13,11 +10,11 @@ use diffsims. .. toctree:: :caption: Usage - :maxdepth: 2 - https://github.com/pyxem/diffsims-demos + :maxdepth: 3 + + Tutorials ../examples/index.rst - installation.rst .. toctree:: :caption: Resources From c6cf175f5b4f71bc7c9a095e7e04b23973b4cc86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ha=CC=8Akon=20Wiik=20A=CC=8Anes?= Date: Sun, 12 May 2024 10:42:56 +0200 Subject: [PATCH 13/13] Add numpydoc config (welcome, build warnings!), fix API minigallery MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Håkon Wiik Ånes --- doc/_templates/custom-attribute-template.rst | 3 +++ doc/_templates/custom-class-template.rst | 9 ++++--- doc/_templates/custom-function-template.rst | 3 +++ doc/_templates/custom-method-template.rst | 3 +++ doc/_templates/custom-module-template.rst | 4 +-- doc/conf.py | 28 +++++++++++++++++++- 6 files changed, 43 insertions(+), 7 deletions(-) diff --git a/doc/_templates/custom-attribute-template.rst b/doc/_templates/custom-attribute-template.rst index c31bebe0..ea206ece 100644 --- a/doc/_templates/custom-attribute-template.rst +++ b/doc/_templates/custom-attribute-template.rst @@ -3,3 +3,6 @@ .. currentmodule:: {{ module }} .. autoproperty:: {{ objname }} + +.. minigallery:: {{ module }}.{{ objname }} + :add-heading: Examples using ``{{ objname }}`` diff --git a/doc/_templates/custom-class-template.rst b/doc/_templates/custom-class-template.rst index 8ada3fb0..8ea2b40f 100644 --- a/doc/_templates/custom-class-template.rst +++ b/doc/_templates/custom-class-template.rst @@ -7,12 +7,11 @@ {% block attributes %} {% if attributes %} .. rubric:: {{ _('Attributes') }} - .. autosummary:: :toctree: :template: custom-attribute-template.rst {% for item in attributes %} - {% if item.0 != item.upper().0 and item not in inherited_members %} + {% if item.0 != item.upper().0 %} {{ name }}.{{ item }} {% endif %} {%- endfor %} @@ -22,14 +21,16 @@ {% block methods %} {% if methods %} .. rubric:: {{ _('Methods') }} - .. autosummary:: :toctree: :template: custom-method-template.rst {% for item in methods %} - {% if item != "__init__" and item not in inherited_members %} + {% if item.0 != item.upper().0 %} {{ name }}.{{ item }} {% endif %} {%- endfor %} {% endif %} {% endblock %} + +.. minigallery:: {{ module }}.{{ objname }} + :add-heading: Examples using ``{{ objname }}`` diff --git a/doc/_templates/custom-function-template.rst b/doc/_templates/custom-function-template.rst index 5ffed09e..b109cab9 100644 --- a/doc/_templates/custom-function-template.rst +++ b/doc/_templates/custom-function-template.rst @@ -3,3 +3,6 @@ .. currentmodule:: {{ module }} .. autofunction:: {{ objname }} + +.. minigallery:: {{ module }}.{{ objname }} + :add-heading: Examples using ``{{ objname }}`` \ No newline at end of file diff --git a/doc/_templates/custom-method-template.rst b/doc/_templates/custom-method-template.rst index 306d2aab..3ebddf87 100644 --- a/doc/_templates/custom-method-template.rst +++ b/doc/_templates/custom-method-template.rst @@ -3,3 +3,6 @@ .. currentmodule:: {{ module }} .. automethod:: {{ objname }} + +.. minigallery:: {{ module }}.{{ objname }} + :add-heading: Examples using ``{{ objname }}`` \ No newline at end of file diff --git a/doc/_templates/custom-module-template.rst b/doc/_templates/custom-module-template.rst index 05d36cd7..f45d4f56 100644 --- a/doc/_templates/custom-module-template.rst +++ b/doc/_templates/custom-module-template.rst @@ -60,8 +60,8 @@ :toctree: :template: custom-module-template.rst :recursive: -{% for item in modules %} + {% for item in modules %} {{ item }} -{%- endfor %} + {%- endfor %} {% endif %} {% endblock %} diff --git a/doc/conf.py b/doc/conf.py index 106e9f18..76a3cd7e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -172,7 +172,33 @@ def linkcode_resolve(domain, info): "examples_dirs": "../examples", # path to your example scripts "gallery_dirs": "examples", # path to where to save gallery generated output "filename_pattern": "^((?!sgskip).)*$", # pattern to define which will be executed - "ignore_pattern": "_sgskip.py", # pattern to define which will not be executed "reference_url": {"diffsims": None}, + "run_stale_examples": False, } autosummary_generate = True + + +# -- numpydoc +# https://numpydoc.readthedocs.io +numpydoc_show_class_members = False +numpydoc_use_plots = True +numpydoc_xref_param_type = True +# fmt: off +numpydoc_validation_checks = { + "all", # All but the following: + "ES01", # Not all docstrings need an extend summary + "EX01", # Examples: Will eventually enforce + "GL01", # Contradicts numpydoc examples + "GL02", # Appears to be broken? + "GL07", # Appears to be broken? + "GL08", # Methods can be documented in super class + "PR01", # Parameters can be documented in super class + "PR02", # Properties with setters might have docstrings w/"Returns" + "PR04", # Doesn't seem to work with type hints? + "RT01", # Abstract classes might not have return sections + "SA01", # Not all docstrings need a "See Also" + "SA04", # "See Also" section does not need descriptions + "SS06", # Not possible to make all summaries one line + "YD01", # Yields: No plan to enforce +} +# fmt: on