Merge remote-tracking branch 'origin/main' into MGComponent

hmlli · hmlli · commit d7c97c52c823 · 2022-09-06T11:49:06.000-07:00
diff --git a/README.md b/README.md
@@ -19,6 +19,28 @@ Following a discussion with a potential contributor, "new contributor" issues ar
 
 [Documentation can be found at docs.crystaltoolkit.org](https://docs.crystaltoolkit.org)
 
+## Example Apps
+
+| Description                                                                                                                                          | Link&emsp;&emsp;&emsp;                                                                                                                                |
+| :--------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`bandstructure.py`**<br>  Demonstrates capabilities of the `BandstructureAndDosComponent` component                                                | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/bandstructure.py)                      |
+| **`basic_hello_structure.py`**<br>  Uses `StructureMoleculeComponent` to show a simple `pymatgen` structure                                          | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/basic_hello_structure.py)              |
+| **`basic_hello_structure_interactive.py`**<br>  Adds a button to the `basic_hello_structure.py` to toggle between two structures interactively       | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/basic_hello_structure_interactive.py)  |
+| **`basic_hello_world.py`**<br>  Bare-bones example showing how to render the text "Hello scientist!" in Dash app                                     | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/basic_hello_world.py)                  |
+| **`diffraction.py`**<br>  Demonstrates capabilities of the `XRayDiffractionComponent` component                                                      | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/diffraction.py)                        |
+| **`diffraction_dynamic.py`**<br>  Adds a button to `diffraction.py` to load a new structure on the fly                                               | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/diffraction_dynamic.py)                |
+| **`diffraction_empty.py`**<br>  Shows `XRayDiffractionComponent` can be mounted without a passing structure                                          | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/diffraction_empty.py)                  |
+| **`kwarg_inputs.py`**<br>  Shows off boolean input (aka toggle), matrix input and slider input components                                            | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/kwarg_inputs.py)                       |
+| **`phase_diagram.py`**<br>  Combines `MPRester.get_entries_in_chemsys()` and the `PhaseDiagram` component to plot the Li-O-Co convex hull            | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/phase_diagram.py)                      |
+| **`pourbaix.py`**<br>  Combines `MPRester.get_pourbaix_entries()` and the `PourbaixDiagramComponent` to plot the Fe-CO Pourbaix diagram              | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/pourbaix.py)                           |
+| **`structure.py`**<br>  Show cases multiple layout options for the `StructureMoleculeComponent`                                                      | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/structure.py)                          |
+| **`structure_magnetic.py`**<br>  Plots a structure with magnetic moments                                                                             | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/structure_magnetic.py)                 |
+| **`transformations.py`**<br>  Combines `StructureMoleculeComponent` and `AllTransformationsComponent` to apply interactive structure transformations | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/transformations.py)                    |
+| **`transformations_minimal.py`**<br>  Shows how to restrict the types of allowed transformations                                                     | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/transformations_minimal.py)            |
+| **`write_structure_screenshot_to_file.py`**<br>  Shows to save interactive structure views as image files                                            | [![View on GitHub]](https://github.com/materialsproject/crystaltoolkit/blob/main/crystal_toolkit/apps/examples/write_structure_screenshot_to_file.py) |
+
+[View on GitHub]: https://img.shields.io/badge/View%20on-GitHub-darkblue?logo=github
+
 ## Team and Contribution Policy
 
 The [Crystal Toolkit Development Team](https://github.com/materialsproject/crystaltoolkit/graphs/contributors) includes:
diff --git a/crystal_toolkit/apps/examples/bandstructure.py b/crystal_toolkit/apps/examples/bandstructure.py
@@ -39,7 +39,7 @@
 ctc.register_crystal_toolkit(app, layout=my_layout)
 
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/basic_hello_world.py b/crystal_toolkit/apps/examples/basic_hello_world.py
@@ -9,7 +9,7 @@
 # create your layout
 app.layout = html.Span(["Hello scientist!"])
 
-# allow app to be run using "python app.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/diffraction.py b/crystal_toolkit/apps/examples/diffraction.py
@@ -27,7 +27,7 @@
 # as explained in "preamble" section in documentation
 ctc.register_crystal_toolkit(app=app, layout=my_layout)
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/diffraction_dynamic.py b/crystal_toolkit/apps/examples/diffraction_dynamic.py
@@ -28,7 +28,7 @@ def load_structure(n_clicks: int) -> Structure:
     return structure
 
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/diffraction_empty.py b/crystal_toolkit/apps/examples/diffraction_empty.py
@@ -1,16 +1,13 @@
 import dash
 
-# create our crystal structure using pymatgen
-from pymatgen.core.lattice import Lattice
-from pymatgen.core.structure import Structure
-
 import crystal_toolkit.components as ctc
 from crystal_toolkit.helpers.layouts import H1, Container
 from crystal_toolkit.settings import SETTINGS
 
-app = dash.Dash(assets_folder=SETTINGS.ASSETS_PATH)
+# create our crystal structure using pymatgen
+
 
-structure = Structure(Lattice.cubic(4.2), ["Na", "K"], [[0, 0, 0], [0.5, 0.5, 0.5]])
+app = dash.Dash(assets_folder=SETTINGS.ASSETS_PATH)
 
 xrd_component = ctc.XRayDiffractionComponent()
 
@@ -22,7 +19,7 @@
 # as explained in "preamble" section in documentation
 ctc.register_crystal_toolkit(app=app, layout=my_layout)
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/kwarg_inputs.py b/crystal_toolkit/apps/examples/kwarg_inputs.py
@@ -88,7 +88,7 @@ def add_inputs(n_clicks):
 # tell Crystal Toolkit about the app and layout we want to display
 ctc.register_crystal_toolkit(app=app, layout=my_layout, cache=None)
 
-# allow app to be run using "python app.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/phase_diagram.py b/crystal_toolkit/apps/examples/phase_diagram.py
@@ -58,7 +58,7 @@
 app.layout = ctc.crystal_toolkit_layout(my_layout)
 
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/pourbaix.py b/crystal_toolkit/apps/examples/pourbaix.py
@@ -32,7 +32,7 @@
 
 ctc.register_crystal_toolkit(app=app, layout=my_layout)
 
-# allow app to be run using "python pourbaix.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/structure.py b/crystal_toolkit/apps/examples/structure.py
@@ -36,7 +36,7 @@
 # tell crystal toolkit about your app and layout
 ctc.register_crystal_toolkit(app, layout=my_layout)
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/structure_magnetic.py b/crystal_toolkit/apps/examples/structure_magnetic.py
@@ -41,7 +41,7 @@
 # tell crystal toolkit about your app and layout
 ctc.register_crystal_toolkit(app, layout=my_layout)
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/transformations.py b/crystal_toolkit/apps/examples/transformations.py
@@ -72,7 +72,7 @@ def update_structure(struct):
     return struct
 
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/apps/examples/transformations_minimal.py b/crystal_toolkit/apps/examples/transformations_minimal.py
@@ -59,7 +59,7 @@ def update_structure(struct):
     return struct
 
 
-# allow app to be run using "python structure.py"
+# run this app with "python path/to/this/file.py"
 # in production, deploy behind gunicorn or similar
 # see Dash documentation for more information
 if __name__ == "__main__":
diff --git a/crystal_toolkit/components/__init__.py b/crystal_toolkit/components/__init__.py
@@ -1,51 +1,69 @@
+# use redundant as-import following PEP 484, see
+# https://github.com/microsoft/pylance-release/issues/856#issuecomment-763793949
+# and https://peps.python.org/pep-0484/#stub-files
+
+from crystal_toolkit.components.bandstructure import (
+    BandstructureAndDosComponent as BandstructureAndDosComponent,
+)
 from crystal_toolkit.components.bandstructure import (
-    BandstructureAndDosComponent,
-    BandstructureAndDosPanelComponent,
+    BandstructureAndDosPanelComponent as BandstructureAndDosPanelComponent,
+)
+from crystal_toolkit.components.diffraction import (
+    TEMDiffractionComponent as TEMDiffractionComponent,
 )
 from crystal_toolkit.components.diffraction import (
-    TEMDiffractionComponent,
-    XRayDiffractionComponent,
+    XRayDiffractionComponent as XRayDiffractionComponent,
 )
-from crystal_toolkit.components.localenv import LocalEnvironmentPanel
 from crystal_toolkit.components.phase_diagram import (
-    PhaseDiagramComponent,
-    PhaseDiagramPanelComponent,
+    PhaseDiagramComponent as PhaseDiagramComponent,
+)
+from crystal_toolkit.components.phase_diagram import (
+    PhaseDiagramPanelComponent as PhaseDiagramPanelComponent,
+)
+from crystal_toolkit.components.pourbaix import (
+    PourbaixDiagramComponent as PourbaixDiagramComponent,
+)
+from crystal_toolkit.components.robocrys import RobocrysComponent as RobocrysComponent
+from crystal_toolkit.components.search import SearchComponent as SearchComponent
+from crystal_toolkit.components.structure import (
+    StructureMoleculeComponent as StructureMoleculeComponent,
 )
-from crystal_toolkit.components.pourbaix import PourbaixDiagramComponent
-from crystal_toolkit.components.robocrys import RobocrysComponent
-from crystal_toolkit.components.search import SearchComponent
-from crystal_toolkit.components.structure import StructureMoleculeComponent
 
-# from crystal_toolkit.components.submit_snl import SubmitSNLPanel
-from crystal_toolkit.components.symmetry import SymmetryPanel
+# from crystal_toolkit.components.submit_snl import SubmitSNLPanel as SubmitSNLPanel
+from crystal_toolkit.components.symmetry import SymmetryPanel as SymmetryPanel
 from crystal_toolkit.components.transformations.autooxistatedecoration import (
-    AutoOxiStateDecorationTransformationComponent,
+    AutoOxiStateDecorationTransformationComponent as AutoOxiStateDecorationTransformationComponent,
+)
+from crystal_toolkit.components.transformations.core import (
+    AllTransformationsComponent as AllTransformationsComponent,
 )
-from crystal_toolkit.components.transformations.core import AllTransformationsComponent
 
 # from crystal_toolkit.components.transformations.cubic import (
-#     CubicSupercellTransformationComponent,
+#     CubicSupercellTransformationComponent as CubicSupercellTransformationComponent,
 # )
 from crystal_toolkit.components.transformations.grainboundary import (
-    GrainBoundaryTransformationComponent,
+    GrainBoundaryTransformationComponent as GrainBoundaryTransformationComponent,
+)
+
+# from crystal_toolkit.components.transformations.rattle import (
+#     MonteCarloRattleTransformationComponent as MonteCarloRattleTransformationComponent,
+# )
+from crystal_toolkit.components.transformations.slab import (
+    SlabTransformationComponent as SlabTransformationComponent,
 )
-from crystal_toolkit.components.transformations.slab import SlabTransformationComponent
 from crystal_toolkit.components.transformations.substitution import (
-    SubstitutionTransformationComponent,
+    SubstitutionTransformationComponent as SubstitutionTransformationComponent,
 )
 from crystal_toolkit.components.transformations.supercell import (
-    SupercellTransformationComponent,
+    SupercellTransformationComponent as SupercellTransformationComponent,
+)
+from crystal_toolkit.components.upload import (
+    StructureMoleculeUploadComponent as StructureMoleculeUploadComponent,
 )
-from crystal_toolkit.components.upload import StructureMoleculeUploadComponent
-from crystal_toolkit.core.mpcomponent import MPComponent
-
-# from crystal_toolkit.components.xas import XASComponent, XASPanelComponent
-
-
-# from crystal_toolkit.components.transformations.rattle import (
-#     MonteCarloRattleTransformationComponent,
-# )
 
+# from crystal_toolkit.components.xas import XASComponent as XASComponent
+# from crystal_toolkit.components.xas import XASPanelComponent as XASPanelComponent
+from crystal_toolkit.core.mpcomponent import MPComponent as MPComponent
 
 register_app = MPComponent.register_app
 register_cache = MPComponent.register_cache
diff --git a/crystal_toolkit/components/structure.py b/crystal_toolkit/components/structure.py
@@ -604,7 +604,7 @@ def get_font_color(hex_code):
         try:
             formula = Composition.from_dict(legend["composition"]).reduced_formula
         except Exception:
-            # TODO: fix legend for Dummy Specie compositions
+            # TODO: fix legend for DummySpecies compositions
             formula = "Unknown"
 
         legend_colors = OrderedDict(
diff --git a/crystal_toolkit/components/transformations/substitution.py b/crystal_toolkit/components/transformations/substitution.py
@@ -38,7 +38,7 @@ def options_layouts(self, state=None, structure=None):
             state=state,
             help_str="A mapping from an original species (element or element with oxidation state, e.g. O or O2-) "
             "to a new species (element, element with oxidation state, or a composition, e.g. O or O2- or "
-            '{"Au": 0.5, "Cu": 0.5}). In pymatgen, these are Element, Specie and Composition classes '
+            '{"Au": 0.5, "Cu": 0.5}). In pymatgen, these are Element, Species and Composition classes '
             "respectively.",
             key_name="Original Species",
             value_name="New Species",
diff --git a/crystal_toolkit/core/legend.py b/crystal_toolkit/core/legend.py
@@ -4,15 +4,15 @@
 import warnings
 from collections import defaultdict
 from itertools import chain
-from typing import Any
+from typing import Any, cast
 
 import numpy as np
 from matplotlib.cm import get_cmap
 from monty.json import MSONable
 from monty.serialization import loadfn
 from palettable.colorbrewer.qualitative import Set1_9
 from pymatgen.analysis.molecule_structure_comparator import CovalentRadius
-from pymatgen.core.periodic_table import Element, Specie
+from pymatgen.core.periodic_table import Element, Species
 from pymatgen.core.structure import Molecule, Site, SiteCollection
 from pymatgen.util.string import unicodeify_species
 from sklearn.preprocessing import LabelEncoder
@@ -134,7 +134,7 @@ def __init__(
         self.color_scheme = color_scheme
         self.radius_scheme = radius_scheme
         self.cmap = cmap
-        self.cmap_range = cmap_range
+        self.cmap_range = cast(tuple[float, float], cmap_range)
 
     @staticmethod
     def generate_accessible_color_scheme_on_the_fly(
@@ -162,12 +162,12 @@ def generate_accessible_color_scheme_on_the_fly(
             (0, 0, 0),  # 0, black
             (230, 159, 0),  # 1, orange
             (86, 180, 233),  # 2, sky blue
-            (0, 158, 115),  #  3, bluish green
+            (0, 158, 115),  # 3, bluish green
             (240, 228, 66),  # 4, yellow
             (0, 114, 178),  # 5, blue
             (213, 94, 0),  # 6, vermilion
             (204, 121, 167),  # 7, reddish purple
-            (255, 255, 255),  #  8, white
+            (255, 255, 255),  # 8, white
         ]
 
         # similar to CPK, mapping element to palette index
@@ -255,13 +255,13 @@ def generate_categorical_color_scheme_on_the_fly(
 
         return color_scheme
 
-    def get_color(self, sp: Specie | Element, site: Site | None = None) -> str:
+    def get_color(self, sp: Species | Element, site: Site | None = None) -> str:
         """
         Get a color to render a specific species. Optionally, you can provide
         a site for context, since ...
 
         Args:
-            sp: Specie or Element
+            sp: Species or Element
             site: Site
 
         Returns: Color
@@ -300,8 +300,7 @@ def get_color(self, sp: Specie | Element, site: Site | None = None) -> str:
                 cmap = get_cmap(self.cmap)
 
                 # normalize in [0, 1] range, as expected by cmap
-                prop_min = self.cmap_range[0]
-                prop_max = self.cmap_range[1]
+                prop_min, prop_max = self.cmap_range
                 prop_normed = (prop - prop_min) / (prop_max - prop_min)
 
                 color = [int(c * 255) for c in cmap(prop_normed)[0:3]]
@@ -333,7 +332,7 @@ def get_color(self, sp: Specie | Element, site: Site | None = None) -> str:
 
         return html5_serialize_simple_color(color)
 
-    def get_radius(self, sp: Specie | Element, site: Site | None = None) -> float:
+    def get_radius(self, sp: Species | Element, site: Site | None = None) -> float:
 
         # allow manual override by user
         if site and "display_radius" in site.properties:
@@ -352,7 +351,7 @@ def get_radius(self, sp: Specie | Element, site: Site | None = None) -> float:
             radius = float(sp.atomic_radius)
         elif (
             self.radius_scheme == "specified_or_average_ionic"
-            and isinstance(sp, Specie)
+            and isinstance(sp, Species)
             and sp.oxi_state
         ):
             radius = float(sp.ionic_radius)
@@ -396,10 +395,10 @@ def analyze_site_props(site_collection: SiteCollection) -> dict[str, list[str]]:
         return dict(site_prop_names)
 
     @staticmethod
-    def get_species_str(sp: Specie | Element) -> str:
+    def get_species_str(sp: Species | Element) -> str:
         """
         Args:
-            sp: Specie or Element
+            sp: Species or Element
 
         Returns: string representation
         """
diff --git a/crystal_toolkit/core/scene.py b/crystal_toolkit/core/scene.py
@@ -48,7 +48,7 @@ class Scene:
 
     name: str  # name for the scene, does not have to be unique
     contents: list = field(default_factory=list)
-    origin: list[float] = field(default=(0, 0, 0))
+    origin: tuple[float, float, float] = field(default=(0, 0, 0))
     visible: bool = True
     lattice: list[list[float]] | None = None
     _meta: dict | None = None
diff --git a/crystal_toolkit/renderables/__init__.py b/crystal_toolkit/renderables/__init__.py
diff --git a/crystal_toolkit/renderables/moleculegraph.py b/crystal_toolkit/renderables/moleculegraph.py
diff --git a/tests/test_chgcar.py b/tests/test_chgcar.py
