Add generic plot widgets and demos

examples/widgets/marimo_demo.py

@@ -53,6 +53,14 @@ def _():
 # === Convex Hull from PhaseDiagram ===
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Convex Hull Widget\n"
+        "Build a compact Li-Fe-O phase diagram and visualize its convex hull."
+    )
+
+
 @app.cell
 def _(Composition, pmv):
     from pymatgen.analysis.phase_diagram import PDEntry, PhaseDiagram
@@ -74,6 +82,14 @@ def _(Composition, pmv):
 # === 3D Structure + Brillouin Zone ===
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Structure Widget\n"
+        "Render a wurtzite GaN crystal with bonds in an interactive 3D view."
+    )
+
+
 @app.cell
 def _(Lattice, Structure, pmv):
     _struct = Structure(
@@ -90,6 +106,14 @@ def _(Lattice, Structure, pmv):
     return (_struct,)
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Brillouin Zone Widget\n"
+        "Show the reciprocal-space Brillouin zone for the structure above."
+    )
+
+
 @app.cell
 def _(_struct, pmv):
     pmv.BrillouinZoneWidget(
@@ -100,6 +124,11 @@ def _(_struct, pmv):
 # === XRD Pattern ===
 
 
+@app.cell
+def _(mo):
+    mo.md("### XRD Widget\nCompute and display an XRD pattern for rutile TiO2.")
+
+
 @app.cell
 def _(Lattice, Structure, pmv):
     from pymatgen.analysis.diffraction.xrd import XRDCalculator
@@ -124,6 +153,15 @@ def _(Lattice, Structure, pmv):
 # === Trajectory with Force Vectors ===
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Trajectory Widget\n"
+        "Generate a short perturbed Fe trajectory and plot structure with "
+        "scalar metadata."
+    )
+
+
 @app.cell
 def _(Lattice, Structure, np, np_rng, pmv):
     _trajectory = []
@@ -148,39 +186,149 @@ def _(Lattice, Structure, np, np_rng, pmv):
     )
 
 
-# === Band Structure + DOS ===
+# === Plot Widgets ===
+
+
+@app.cell
+def _(mo):
+    mo.md(
+        "### Scatter Plot Widget\n"
+        "Dual-axis comparison of `sin(x)` and `cos(x)` with shared x-values."
+    )
 
 
 @app.cell
 def _(np, pmv):
-    _band_data = {
-        "@module": "pymatgen.electronic_structure.bandstructure",
-        "@class": "BandStructureSymmLine",
-        "bands": {
-            "1": [[0.5 * np.sin(k / 10) + idx for k in range(50)] for idx in range(4)]
+    scatter_series = [
+        {
+            "label": "sin(x)",
+            "x": np.linspace(0, 6.0, 60).tolist(),
+            "y": np.sin(np.linspace(0, 6.0, 60)).tolist(),
         },
-        "efermi": 0.0,
-        "kpoints": [[k / 50, 0, 0] for k in range(50)],
-        "labels_dict": {"\\Gamma": [0, 0, 0], "X": [0.5, 0, 0], "M": [0.5, 0.5, 0]},
-        "lattice_rec": {"matrix": [[1, 0, 0], [0, 1, 0], [0, 0, 1]]},
-    }
+        {
+            "label": "cos(x)",
+            "x": np.linspace(0, 6.0, 60).tolist(),
+            "y": np.cos(np.linspace(0, 6.0, 60)).tolist(),
+            "y_axis": "y2",
+        },
+    ]
+    pmv.ScatterPlotWidget(
+        series=scatter_series,
+        x_axis={"label": "x"},
+        y_axis={"label": "sin(x)"},
+        y2_axis={"label": "cos(x)", "color": "#ff7f0e"},
+        display={"x_grid": True, "y_grid": True},
+        legend={"position": "top-right"},
+        style="height: 420px;",
+    )
+    return (scatter_series,)
+
+
+@app.cell
+def _(mo):
+    mo.md(
+        "### Bar Plot Widget\n"
+        "Grouped bars compare two model scores across the same sample indices."
+    )
+
+
+@app.cell
+def _(pmv):
+    bar_series = [
+        {"label": "Model A", "x": [0, 1, 2], "y": [4.2, 5.1, 4.8]},
+        {"label": "Model B", "x": [0, 1, 2], "y": [3.9, 4.6, 5.2]},
+    ]
+    pmv.BarPlotWidget(
+        series=bar_series,
+        mode="grouped",
+        x_axis={"label": "Sample index"},
+        y_axis={"label": "Score"},
+        display={"y_grid": True},
+        style="height: 360px;",
+    )
+
+
+@app.cell
+def _(mo):
+    mo.md(
+        "### Histogram Widget\n"
+        "Overlaid histograms show the distributions of the two trigonometric series."
+    )
+
+
+@app.cell
+def _(scatter_series, pmv):
+    histogram_series = [
+        {
+            "label": scatter_series[0]["label"],
+            "x": scatter_series[0]["x"],
+            "y": scatter_series[0]["y"],
+        },
+        {
+            "label": scatter_series[1]["label"],
+            "x": scatter_series[1]["x"],
+            "y": scatter_series[1]["y"],
+        },
+    ]
+    pmv.HistogramWidget(
+        series=histogram_series,
+        bins=20,
+        mode="overlay",
+        x_axis={"label": "Value"},
+        y_axis={"label": "Count"},
+        style="height: 360px;",
+    )
+
+
+# === Band Structure + DOS ===
+
+
+@app.cell
+def _(mo):
+    mo.md(
+        "### Band Structure Widget\n"
+        "Load realistic phonon band structure data from test fixtures."
+    )
+
+
+@app.cell
+def _(pmv):
+    import json
+
+    from monty.io import zopen
+    from monty.json import MontyDecoder
+
+    from pymatviz.utils.testing import TEST_FILES
+
+    _phonon_fixture_path = f"{TEST_FILES}/phonons/mp-2758-Sr4Se4-pbe.json.xz"
+    with zopen(_phonon_fixture_path, mode="rt") as file:
+        _phonon_doc = json.loads(file.read(), cls=MontyDecoder)
+
+    _band_data = _phonon_doc.phonon_bandstructure
     pmv.BandStructureWidget(band_structure=_band_data, style="height: 400px;")
-    return (_band_data,)
+    return _band_data, _phonon_doc
 
 
 @app.cell
-def _(np, pmv):
-    _dos_data = {
-        "@module": "pymatgen.electronic_structure.dos",
-        "@class": "Dos",
-        "energies": np.linspace(-5, 5, 200).tolist(),
-        "densities": {"1": np.exp(-0.5 * np.linspace(-5, 5, 200) ** 2).tolist()},
-        "efermi": 0.0,
-    }
+def _(mo):
+    mo.md("### DOS Widget\nUse matching phonon DOS data from the same fixture.")
+
+
+@app.cell
+def _(_phonon_doc, pmv):
+    _dos_data = _phonon_doc.phonon_dos
     pmv.DosWidget(dos=_dos_data, style="height: 400px;")
     return (_dos_data,)
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Bands + DOS Widget\n"
+        "Combine bands and DOS into a coordinated electronic-structure view."
+    )
+
+
 @app.cell
 def _(_band_data, _dos_data, pmv):
     pmv.BandsAndDosWidget(
@@ -191,6 +339,14 @@ def _(_band_data, _dos_data, pmv):
 # === Composition Grid ===
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Composition Widgets Grid\n"
+        "Compare several compositions across pie, bar, and bubble modes."
+    )
+
+
 @app.cell
 def _(Composition, mo, pmv):
     _comps = (
@@ -221,6 +377,15 @@ def _(Composition, mo, pmv):
 # === Remote Trajectory Files ===
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Local Trajectory From Download\n"
+        "Download a trajectory file once, cache it, and visualize it from "
+        "local storage."
+    )
+
+
 @app.cell
 def _(Final, os, pmv):
     matterviz_traj_dir_url: Final = (
@@ -244,6 +409,14 @@ def _(Final, os, pmv):
     return (matterviz_traj_dir_url,)
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### Remote Trajectory URL\n"
+        "Render a trajectory directly from a remote URL with force vectors and bonds."
+    )
+
+
 @app.cell
 def _(matterviz_traj_dir_url, pmv):
     _file_name = "Cr0.25Fe0.25Co0.25Ni0.25-mace-omat-qha.xyz.gz"
@@ -262,20 +435,44 @@ def _(matterviz_traj_dir_url, pmv):
 # === MIME Type Auto-display ===
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### ASE Atoms MIME Rendering\n"
+        "Display an ASE bulk structure via pymatviz MIME auto-rendering."
+    )
+
+
 @app.cell
 def _(bulk):
     _ase_atoms = bulk("Al", "fcc", a=4.05)
     _ase_atoms *= (2, 2, 2)
     _ase_atoms
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### ASE Molecule MIME Rendering\n"
+        "Display an ASE molecule via pymatviz MIME auto-rendering."
+    )
+
+
 @app.cell
 def _(molecule):
     _ase_molecule = molecule("H2O")
     _ase_molecule.center(vacuum=3.0)
     _ase_molecule
 
 
+@app.cell
+def _(mo):
+    mo.md(
+        "### PhonopyAtoms MIME Rendering\n"
+        "Display a PhonopyAtoms structure via pymatviz MIME auto-rendering."
+    )
+
+
 @app.cell
 def _(PhonopyAtoms):
     PhonopyAtoms(