Interactive viewers with chemiscope 0.7 (#64)

Interactive viewers with chemiscope 0.7
Co-authored-by: Sofiia Chorna <[email protected]>

docs/requirements.txt

@@ -2,3 +2,4 @@ sphinx
 sphinx-gallery
 sphinx-toggleprompt
 furo
+chemiscope>=0.7

docs/src/conf.py

@@ -6,6 +6,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.intersphinx",
     "sphinx_gallery.load_style",
+    "chemiscope.sphinx",
 ]
 
 templates_path = ["_templates"]

examples/dos-align/README.rst

@@ -1,5 +1,5 @@
 Optimizing the energy reference of the DOS during training
-==============================================
+==========================================================
 
 This example illustrates how one can optimize the energy reference of the
 DOS during model training. The dataset consists 104 Silicon diamond structures.

examples/dos-align/environment.yml

@@ -5,7 +5,7 @@ dependencies:
   - pip
   - rust > 1.65
   - pip:
-    - ase
+    - ase==3.22.1
     - matplotlib
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983
     - torch

examples/gaas-map/environment.yml

@@ -5,8 +5,8 @@ dependencies:
   - pip
   - rust >=1.65
   - pip:
-    - ase
-    - chemiscope
+    - ase==3.22.1
+    - chemiscope>=0.7
     - matplotlib
     - metatensor
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983

examples/gaas-map/gaas-map.py

@@ -246,10 +246,6 @@
     },
 )
 
-# shows chemiscope if run in a jupyter environment
-if chemiscope.jupyter._is_running_in_notebook():
-    from IPython.display import display
+cs.save("gaas_map.chemiscope.json.gz")
 
-    display(cs)
-else:
-    cs.save("gaas_map.chemiscope.json.gz")
+cs  # display if in a notebook

examples/lode-linear/environment.yml

@@ -5,7 +5,7 @@ dependencies:
   - pip
   - rust >=1.65
   - pip:
-    - ase
+    - ase==3.22.1
     - equisolve @ git+https://github.com/lab-cosmo/equisolve.git@c858bedef4b2799eb445e4c92535ee387224089a
     - matplotlib
     - metatensor

examples/lpr/environment.yml

@@ -5,8 +5,7 @@ dependencies:
   - pip
   - rust >=1.65
   - pip:
-    - ase
-    - chemiscope
+    - ase==3.22.1
     - matplotlib
     - rascaline @ git+https://github.com/Luthaf/rascaline@5c2a79838bda0a52d0fde2fbe65941f4792c4cae
     - skmatter

examples/path-integrals/environment.yml

@@ -5,8 +5,8 @@ dependencies:
   - pip
   - lammps  
   - pip:
-    - ase
+    - ase==3.22.1
+    - chemiscope>=0.7
     - ipi  
-    - chemiscope
     - matplotlib
     - skmatter

examples/path-integrals/path-integrals.py

@@ -194,14 +194,7 @@
     )
 )
 
-cs = chemiscope.show(**traj_pimd, mode="structure")
-
-if chemiscope.jupyter._is_running_in_notebook():
-    from IPython.display import display
-
-    display(cs)
-else:
-    cs.save("path-integrals.json.gz")
+chemiscope.show(**traj_pimd, mode="structure")
 
 # %%
 # Accelerating PIMD with a PIGLET thermostat
@@ -317,7 +310,7 @@
     [centroid], "kinetic_cv", scale=15, force_positive=True
 )
 
-cs = chemiscope.show(
+chemiscope.show(
     [centroid],
     shapes={"kinetic_cv": ellipsoids},
     mode="structure",
@@ -328,12 +321,3 @@
         }
     ),
 )
-
-# %%
-
-if chemiscope.jupyter._is_running_in_notebook():
-    from IPython.display import display
-
-    display(cs)
-else:
-    cs.save("path-integrals.json.gz")

examples/roy-gch/environment.yml

@@ -5,9 +5,10 @@ dependencies:
   - pip
   - rust >=1.65
   - pip:
-    - ase
-    - chemiscope
+    - ase==3.22.1
+    - chemiscope>=0.7
     - matplotlib
     - metatensor
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983
+    - scikit-learn==1.4.0
     - skmatter

examples/roy-gch/roy-gch.py

@@ -5,9 +5,8 @@
 :Authors: Michele Ceriotti `@ceriottm <https://github.com/ceriottm/>`_
 
 This notebook analyzes the structures of 264 polymorphs of ROY, from
-`Beran et Al, Chemical Science
-(2022) <https://doi.org/10.1039/D1SC06074K>`__, comparing the
-conventional density-energy convex hull with a Generalized Convex Hull
+`Beran et Al, Chemical Science (2022) <https://doi.org/10.1039/D1SC06074K>`__,
+comparing the conventional density-energy convex hull with a Generalized Convex Hull
 (GCH) analysis (see `Anelli et al., Phys. Rev. Materials
 (2018) <https://doi.org/10.1103/PhysRevMaterials.2.103804>`__).
 It uses features computed with `rascaline <https://github.com/lab-cosmo/rascaline>`__
@@ -90,9 +89,7 @@
 # Interactive visualization
 # ^^^^^^^^^^^^^^^^^^^^^^^^^
 #
-# You can also visualize the hull with ``chemiscope``.
-# This runs only in a notebook, and
-# requires having the ``chemiscope`` package installed.
+# You can also visualize the hull with ``chemiscope`` in a juptyer notebook.
 #
 
 cs = chemiscope.show(
@@ -114,14 +111,12 @@
         "structure": [{"unitCell": True, "supercell": {"0": 2, "1": 2, "2": 2}}],
     },
 )
+cs
 
-
-if chemiscope.jupyter._is_running_in_notebook():
-    from IPython.display import display
-
-    display(cs)
-else:
-    cs.save("roy_ch.json.gz")
+# %%
+#
+# Save chemiscope file in a format that can be shared and viewed on `chemiscope.org`
+cs.save("roy_ch.json.gz")
 
 # %%
 # Generalized Convex Hull
@@ -228,18 +223,18 @@
 
 
 # %%
-# Visualize in ``chemiscope``. This runs only in a notebook, and
-# requires having the ``chemiscope`` package installed.
+# Visualize in a ``chemiscope`` widget
 
 for i, f in enumerate(structures):
     for j in range(len(pca_features[i])):
         f.info["pca_" + str(j + 1)] = pca_features[i, j]
 structure_properties = chemiscope.extract_properties(structures)
 structure_properties.update({"per_atom_energy": energy, "hull_energy": dch_dist})
 
-# shows chemiscope if not run in terminal
+# You can save a chemiscope file to disk (for viewing on chemiscope.org)
 
-cs = chemiscope.show(
+chemiscope.write_input(
+    "roy_gch.json.gz",
     frames=structures,
     properties=structure_properties,
     meta={
@@ -286,9 +281,8 @@
     },
 )
 
-if chemiscope.jupyter._is_running_in_notebook():
-    from IPython.display import display
+# %%
+#
+# ... and also load one as an interactive viewer
 
-    display(cs)
-else:
-    cs.save("roy_gch.json.gz")
+chemiscope.show_input("roy_gch.json.gz")

examples/sample-selection/environment.yml

@@ -5,8 +5,8 @@ dependencies:
   - pip
   - rust >=1.65
   - pip:
-    - ase
-    - chemiscope
+    - ase==3.22.1
+    - chemiscope>=0.7
     - matplotlib
     - metatensor
     - rascaline @ git+https://github.com/Luthaf/rascaline@ca957642f512e141c7570e987aadc05c7ac71983

examples/sample-selection/sample-selection.py

@@ -210,9 +210,6 @@
 # descriptors. The resulting PC coordinates can be used to visualize the the
 # data alongside their structures in a chemiscope widget.
 #
-# Note: chemiscope widgets are not currently integrated into our sphinx gallery:
-# coming soon.
-
 
 # Generate a structure PCA
 struct_soap_pca = PCA(n_components=2).fit_transform(struct_soap.block(0).values)
@@ -246,7 +243,6 @@
 # Creates a chemiscope viewer
 # ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 #
-# Interactive viewer (only works in notebooks)
 
 # Selected level
 selection_levels = []
@@ -276,9 +272,6 @@
     }
 )
 
-
-# Display with chemiscope. This currently does not work - as raised in issue #8
-# https://github.com/lab-cosmo/software-cookbook/issues/8
 widget = chemiscope.show(
     frames,
     properties=properties,
@@ -293,14 +286,10 @@
         "structure": [{"unitCell": True}],
     },
 )
+widget.save("sample-selection.json.gz")
 
-if chemiscope.jupyter._is_running_in_notebook():
-    from IPython.display import display
-
-    display(widget)
-else:
-    widget.save("sample-selection.json.gz")
-
+# display, if in notebook or sphinx
+widget
 
 # %%
 # Perform feature selection

generate-gallery.py

@@ -2,7 +2,9 @@
 import shutil
 import sys
 
+import chemiscope  # noqa: F401
 import sphinx_gallery.gen_gallery
+from chemiscope.sphinx import ChemiscopeScraper
 
 
 HERE = os.path.realpath(os.path.dirname(__file__))
@@ -40,14 +42,18 @@ def __init__(self, example):
             "min_reported_time": 60,
             "copyfile_regex": r".*\.(sh|xyz|cp2k|yml|png)",
             "matplotlib_animations": True,
+            "within_subsection_order": "FileNameSortKey",
+            "image_scrapers": ("matplotlib", ChemiscopeScraper()),
         }
 
         self.builder = AttrDict()
         self.builder.srcdir = os.path.join(HERE, "docs", "src")
         self.builder.outdir = ""
         self.builder.name = os.path.basename(example)
 
-        self.extensions = []
+        self.extensions = [
+            "chemiscope.sphinx",
+        ]
 
         self.builder.config = AttrDict()
         self.builder.config.plot_gallery = "True"
@@ -64,7 +70,6 @@ def add_css_file(self, path):
         sys.exit(1)
 
     app = PseudoSphinxApp(example=sys.argv[1])
-
     sphinx_gallery.gen_gallery.fill_gallery_conf_defaults(app, app.config)
     sphinx_gallery.gen_gallery.update_gallery_conf_builder_inited(app)
     sphinx_gallery.gen_gallery.generate_gallery_rst(app)

noxfile.py

@@ -133,7 +133,13 @@ def example(session, name=name):
             )
 
             # install sphinx-gallery and its dependencies
-            session.install("sphinx-gallery", "sphinx", "pillow", "matplotlib")
+            session.install(
+                "sphinx-gallery",
+                "sphinx",
+                "pillow",
+                "matplotlib",
+                "chemiscope",
+            )
 
         session.run("python", "generate-gallery.py", f"examples/{name}")
         os.unlink(f"docs/src/examples/{name}/index.rst")