diff --git a/docs/_templates/sidebar-toc.html b/docs/_templates/sidebar-toc.html index c9c35541b..409e41366 100644 --- a/docs/_templates/sidebar-toc.html +++ b/docs/_templates/sidebar-toc.html @@ -1 +1 @@ -{{ toctree(maxdepth=2|toint, collapse=False, includehidden=theme_globaltoc_includehidden|tobool) }} +{{ toctree(maxdepth=2|toint, collapse=True, includehidden=True) }} diff --git a/docs/src/conf.py b/docs/src/conf.py index 6d20c54f1..269e9423d 100644 --- a/docs/src/conf.py +++ b/docs/src/conf.py @@ -46,7 +46,7 @@ "examples_dirs": os.path.join(ROOT, "python", "examples"), "gallery_dirs": "examples", "filename_pattern": ".*", - "within_subsection_order": "ExampleTitleSortKey", + "within_subsection_order": "FileNameSortKey", } # -- Options for HTML output ------------------------------------------------- diff --git a/docs/src/examples.rst b/docs/src/examples.rst index 1b526fdeb..362e55846 100644 --- a/docs/src/examples.rst +++ b/docs/src/examples.rst @@ -10,6 +10,14 @@ consist in short Python scripts that demonstrate how to make a chemiscope viewer file that uses some particular features (e.g. atom coloring or shape visualization). +.. toctree:: + + examples/base + examples/structure_map + examples/trajectory + examples/colors + examples/shapes + .. raw:: html

Basic usage

diff --git a/docs/src/index.rst b/docs/src/index.rst index 02ff9f7fd..5518bd412 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -39,16 +39,14 @@ back to the `chemiscope`_ homepage is the preferred form of acknowledgement. What's in this documentation? ----------------------------- -.. toctree:: - :hidden: - - Chemiscope visualizer - + .. toctree:: :maxdepth: 2 - - examples - manual/index + + Chemiscope visualizer + examples + manual/index + python/index embedding diff --git a/docs/src/manual/index.rst b/docs/src/manual/index.rst index e3fb88a1c..d058ae776 100644 --- a/docs/src/manual/index.rst +++ b/docs/src/manual/index.rst @@ -24,7 +24,4 @@ extension, which can be used to explore a dataset directly inside a jupyter note properties panels input - python - jupyter sharing - gallery diff --git a/docs/src/manual/python.rst b/docs/src/manual/python.rst deleted file mode 100644 index afa575780..000000000 --- a/docs/src/manual/python.rst +++ /dev/null @@ -1,71 +0,0 @@ -.. _python-module: - -Python module -============= - -The `chemiscope` package provides utilities to prepare JSON input files, -and to visualize them in a :ref:`jupyter environment `. -The package also provides a small set of utility functions to convert `ase`_ -structure data, and a command-line command to convert structure files to -a JSON input. - - -Installation ------------- - -The latest release of the `chemiscope` Python package can be installed from -the Python package index, using - -.. code-block:: - - pip install chemiscope - -To install a development version, one should instead clone the -`github repository `_, -make sure that all the dependencies (including those needed to compile -the typescript library) are present and then run - -.. code-block:: - - pip install . - -in the main folder. - - - -``chemiscope`` functions reference ----------------------------------- - -.. autofunction:: chemiscope.write_input - -.. autofunction:: chemiscope.create_input - -.. autofunction:: chemiscope.quick_settings - -.. autofunction:: chemiscope.extract_properties - -.. autofunction:: chemiscope.composition_properties - -.. autofunction:: chemiscope.all_atomic_environments - -.. autofunction:: chemiscope.librascal_atomic_environments - -.. autofunction:: chemiscope.ellipsoid_from_tensor - -.. autofunction:: chemiscope.arrow_from_vector - -.. autofunction:: chemiscope.ase_vectors_to_arrows - -.. autofunction:: chemiscope.ase_tensors_to_ellipsoids - -.. _chemiscope-input-cli: - -``chemiscope-input`` command line interface -------------------------------------------- - -.. sphinx_argparse_cli:: - :module: chemiscope.main - :func: _chemiscope_input_parser - :prog: chemiscope-input - :title: - :group_title_prefix: diff --git a/docs/src/python/cli.rst b/docs/src/python/cli.rst new file mode 100644 index 000000000..fee52f8d4 --- /dev/null +++ b/docs/src/python/cli.rst @@ -0,0 +1,9 @@ +Command line interface +----------------------- + +.. sphinx_argparse_cli:: + :module: chemiscope.main + :func: _chemiscope_input_parser + :prog: chemiscope-input + :title: + :group_title_prefix: diff --git a/docs/src/manual/gallery.rst b/docs/src/python/gallery.rst similarity index 100% rename from docs/src/manual/gallery.rst rename to docs/src/python/gallery.rst diff --git a/docs/src/python/index.rst b/docs/src/python/index.rst new file mode 100644 index 000000000..2eb07375e --- /dev/null +++ b/docs/src/python/index.rst @@ -0,0 +1,23 @@ +.. _python-module: + +Python module +============= + +The `chemiscope` package provides utilities to prepare JSON input files, +and to visualize them in a :ref:`jupyter environment `. +The package also provides a small set of utility functions to convert `ase`_ +structure data, and a command-line command to convert structure files to +a JSON input. + +.. toctree:: + :maxdepth: 2 + + installation + cli + reference + jupyter + gallery + + +.. _ase: https://wiki.fysik.dtu.dk/ase/index.html + diff --git a/docs/src/python/installation.rst b/docs/src/python/installation.rst new file mode 100644 index 000000000..648530494 --- /dev/null +++ b/docs/src/python/installation.rst @@ -0,0 +1,20 @@ +Installation +------------ + +The latest release of the `chemiscope` Python package can be installed from +the Python package index, using + +.. code-block:: + + pip install chemiscope + +To install a development version, one should instead clone the +`github repository `_, +make sure that all the dependencies (including those needed to compile +the typescript library) are present and then run + +.. code-block:: + + pip install . + +in the main folder. diff --git a/docs/src/manual/jupyter.rst b/docs/src/python/jupyter.rst similarity index 100% rename from docs/src/manual/jupyter.rst rename to docs/src/python/jupyter.rst diff --git a/docs/src/python/reference.rst b/docs/src/python/reference.rst new file mode 100644 index 000000000..c6d503da5 --- /dev/null +++ b/docs/src/python/reference.rst @@ -0,0 +1,28 @@ +.. _reference: + +``chemiscope`` functions reference +---------------------------------- + +.. autofunction:: chemiscope.write_input + +.. autofunction:: chemiscope.create_input + +.. autofunction:: chemiscope.quick_settings + +.. autofunction:: chemiscope.extract_properties + +.. autofunction:: chemiscope.composition_properties + +.. autofunction:: chemiscope.all_atomic_environments + +.. autofunction:: chemiscope.librascal_atomic_environments + +.. autofunction:: chemiscope.ellipsoid_from_tensor + +.. autofunction:: chemiscope.arrow_from_vector + +.. autofunction:: chemiscope.ase_vectors_to_arrows + +.. autofunction:: chemiscope.ase_tensors_to_ellipsoids + +.. _chemiscope-input-cli: diff --git a/python/examples/base.py b/python/examples/base.py index c6492c15d..04f3bb5b8 100644 --- a/python/examples/base.py +++ b/python/examples/base.py @@ -15,15 +15,16 @@ import chemiscope # %% +# # Load structures from an extended xyz file frames = ase.io.read("data/showcase.xyz", ":") # %% -# Write a chemiscope input file. +# +# Uses a chemiscope widget to visualize structures and properties -chemiscope.write_input( - path="showcase.json.gz", +cs = chemiscope.show( frames=frames, # quickly extract properties from the ASE frames. nb: if you're doing this for # sharing, don't forget to also include metadata such as units and description @@ -37,8 +38,10 @@ x="ccsd_pol[1]", y="ccsd_pol[2]", color="dipole_ccsd[1]" ), ) +cs # %% -# Use `chemiscope.show` to view directly in a Jupyter environment +# +# Save as a file that can be viewed at chemiscope.org -chemiscope.show(frames, properties=chemiscope.extract_properties(frames)) +cs.save("showcase.json.gz") diff --git a/python/examples/colors.py b/python/examples/colors.py index 3db06835c..07073c5e2 100644 --- a/python/examples/colors.py +++ b/python/examples/colors.py @@ -18,20 +18,20 @@ # %% # -# loads a dataset of structures containing polarizability and dipole data +# Load a dataset of structures containing polarizability and dipole data frames = ase.io.read("data/alpha-mu.xyz", ":") # %% # -# compute some scalar quantities to display as atom coloring +# Compute some scalar quantities to display as atom coloring polarizability = [] alpha_eigenvalues = [] anisotropy = [] for frame in frames: - # center in the box + # center molecule in the box frame.positions += frame.cell.diagonal() * 0.5 for axx, ayy, azz, axy, axz, ayz in zip( frame.arrays["axx"], @@ -53,17 +53,17 @@ # %% # -# now we just write the chemiscope input file +# Now we just display the chemiscope (if running in a notebook) cs = chemiscope.show( frames=frames, - # properties can be extracted from the ASE.Atoms frames + # properties can also be extracted from the ASE.Atoms frames properties={ "polarizability": np.vstack(polarizability), "anisotropy": np.vstack(anisotropy), "alpha_eigenvalues": np.vstack(alpha_eigenvalues), }, - # the write_input function also allows defining the default visualization settings + # it is also possible to define the default visualization settings settings={ "map": { "x": {"property": "alpha_eigenvalues[1]"}, @@ -78,15 +78,14 @@ ], }, # the properties we want to visualise are atomic properties - in order to view them - # in the map panel, we must indicate that all atoms are environment centers + # in the map panel, we must indicate the list of environments (all atoms, in this case) environments=chemiscope.all_atomic_environments(frames), ) cs # %% -# -# also saves as a file +# +# Save as a file that can be viewed at chemiscope.org cs.save("colors-example.json.gz") - diff --git a/python/examples/shapes.py b/python/examples/shapes.py index f9c82ac70..48e5797f6 100644 --- a/python/examples/shapes.py +++ b/python/examples/shapes.py @@ -1,6 +1,6 @@ """ -Extended shape visualization in chemiscope -========================================== +Shape visualization +=================== This example demonstrates how to visualize structure and atomic properties in the structure panel, using different types of @@ -11,13 +11,18 @@ to visualize an interactive widget in a Jupyter notebook. """ +# %% +# + import ase.io import numpy as np from scipy.spatial.transform import Rotation - import chemiscope -# loads a dataset of structures +# %% +# +# Loads a dataset of structures + frames = ase.io.read("data/alpha-mu.xyz", ":") quaternions = [] @@ -49,12 +54,20 @@ R[:, -1] = vec quaternions.append(Rotation.from_matrix(R).as_quat()) -# here we define shapes that will later be used to create the input; +# %% +# +# Shapes generation +# ----------------- +# +# Here we define shapes that will later be used to create the input; # input generation can also be achieved as a single call, but in practice # it is wise to define separate entities for better readability -# cubes with smooth shading, centered on atoms. these are created as +# %% +# +# Cubes with smooth shading, centered on atoms. these are created as # "custom" shapes and then are just scaled to atom-dependent sizes + atom_sizes = {"O": 0.4, "N": 0.5, "C": 0.45, "H": 0.2} smooth_cubes = dict( kind="custom", @@ -95,8 +108,11 @@ }, ) -# structure-based shapes. also demonstrates how to achieve sharp-edge shading. +# %% +# +# Structure-based shapes. also demonstrates how to achieve sharp-edge shading. # requires defining multiple times the same vertices + sharp_cubes = dict( kind="custom", parameters={ @@ -157,7 +173,9 @@ }, ) -# loads vertices and simplices from an external file +# %% +# +# Load vertices and simplices from an external file # and use it to draw a very irreverent molecule irreverent_dict = np.load("data/irreverence.npz") irreverent_shape = dict( @@ -174,7 +192,10 @@ ], }, ) -# dipole moments visualized as arrows. this is just to demonstrate manual insertion, + +# %% +# +# Dipole moments visualized as arrows. this is just to demonstrate manual insertion, # see below to extract directly from the ASE info dipoles_manual = ( dict( @@ -200,6 +221,7 @@ ), ) + dipoles_auto = chemiscope.ase_vectors_to_arrows(frames, "dipole_ccsd", scale=0.5) # one can always update the defaults created by these automatic functions dipoles_auto["parameters"]["global"] = { @@ -213,8 +235,12 @@ ]: # center the dipoles close to the molecule d["position"] = [11, 11, 11] -chemiscope.write_input( - "shapes-example.json.gz", +# %% +# +# +# Uses a chemiscope widget to visualize structures including the custom shapes. +# Even though we have property data, we show a `structure` view of the data +cs = chemiscope.show( frames=frames, properties=chemiscope.extract_properties(frames, only=["alpha"]), shapes={ @@ -262,4 +288,11 @@ ], }, environments=chemiscope.all_atomic_environments(frames), + mode="structure", ) +cs + +# %% +# +# Save as a file that can be viewed at chemiscope.org +cs.save("shapes-example.json.gz") diff --git a/python/examples/structure_map.py b/python/examples/structure_map.py index 4e07dc465..123d99d31 100644 --- a/python/examples/structure_map.py +++ b/python/examples/structure_map.py @@ -1,6 +1,6 @@ """ -Structure-property maps in chemiscope -===================================== +Structure-property maps +======================= This example demonstrates the visualization of structures (or environments) using data-driven descriptors of their geometry, to cluster together similar motifs. Here the @@ -11,27 +11,38 @@ widget in a Jupyter notebook. """ +# %% +# + import ase.io import numpy as np - import chemiscope -# load structures +# %% +## Load structures + frames = ase.io.read("data/trajectory.xyz", ":") -# load the SOAP-PCA descriptors. chemiscope does not provide -# analysis routines, but you can look up for instance +# %% +# +# Load the SOAP-PCA descriptors. chemiscope does not provide +# analysis routines (yet), but you can look up for instance # scikit-matter as a package to do dimensionality reduction # analyses. + pca_atom = np.loadtxt("data/trajectory-pca_atom.dat") pca_struc = np.loadtxt("data/trajectory-pca_structure.dat") -# when both environments and structure property are present -# only environment properties are shown. still they can be stored, +# %% +# +# When both environments and structure property are present +# only environment properties are shown. Still they can be stored, # and future versions of chemiscope may allow switching between # the two modes. +# # NB: if there are properties stored in the ASE frames, you can extract # them with chemiscope.extract_properties(frames) + properties = { # concise definition of a property, with just an array and the type # inferred by the size @@ -46,7 +57,9 @@ }, } -# environment descriptors have only been computed for C and O atoms. +# %% +# +# Environment descriptors have only been computed for C and O atoms. # we use a mask and then a utility function to generate the proper # list of environments for frame in frames: @@ -56,9 +69,12 @@ environments = chemiscope.librascal_atomic_environments(frames, cutoff=4.0) -# write the chemiscope input file. -chemiscope.write_input( - path="trajectory-pca.json.gz", + +# %% +# +# Create and display the chemiscope widget + +cs = chemiscope.show( # dataset metadata can also be included, to provide a self-contained description # of the data, authors and references meta={ @@ -83,3 +99,9 @@ "structure": [{"keepOrientation": True, "playbackDelay": 100}] }, ) +cs + +# %% +# +# Save as a file that can be viewed at chemiscope.org +cs.save("trajectory-pca.json.gz") diff --git a/python/examples/trajectory.py b/python/examples/trajectory.py index a5e9aad81..0848e64b9 100644 --- a/python/examples/trajectory.py +++ b/python/examples/trajectory.py @@ -9,12 +9,17 @@ widget in a Jupyter notebook. """ +# %% +# + import ase.io import numpy as np - import chemiscope -# load structures + +# %% +# +# Load structures and properties frames = ase.io.read("data/trajectory.xyz", ":") properties = { @@ -30,9 +35,13 @@ }, } -# write the chemiscope input file. -chemiscope.write_input( - path="trajectory-md.json.gz", + +# %% +# +# Uses a chemiscope widget to visualize structures and properties. +# Note how to display the forces as vectorial properties + +cs = chemiscope.show( # dataset metadata can also be included, to provide a self-contained description # of the data, authors and references meta={ @@ -67,3 +76,9 @@ ] }, ) +cs + +# %% +# +# Save as a file that can be viewed at chemiscope.org +cs.save("trajectory-md.json.gz")