Setup examples/tutorials for the C API

docs/generate_examples/conf.py

@@ -13,16 +13,16 @@
 HERE = os.path.dirname(__file__)
 ROOT = os.path.realpath(os.path.join(HERE, "..", ".."))
 
+EXAMPLES = ["c", "torch", "ase", "torchsim"]
 
 sphinx_gallery_conf = {
-    "filename_pattern": ".*",
+    "filename_pattern": r"\.py",
     "copyfile_regex": r".*\.(example|mts|xyz)",
-    "examples_dirs": [
-        os.path.join(ROOT, "python", "examples"),
-    ],
+    "examples_dirs": [os.path.join(ROOT, "examples", e) for e in EXAMPLES],
     "gallery_dirs": [
-        os.path.join(ROOT, "docs", "src", "examples"),
+        os.path.join(ROOT, "docs", "src", "examples", e) for e in EXAMPLES
     ],
+    "example_extensions": {".py", ".c", ".cpp"},
     "matplotlib_animations": False,
     "image_scrapers": ("matplotlib", ChemiscopeScraper()),
     "remove_config_comments": True,

docs/src/.gitignore

@@ -1,2 +1,3 @@
-examples/
 sg_execution_times.rst
+examples/*
+!examples/index.rst

docs/src/conf.py

@@ -20,6 +20,7 @@
 import lammps_lexer  # noqa: E402
 from sphinx.highlighting import lexers  # noqa: E402
 
+
 lexers["LAMMPS"] = lammps_lexer.LAMMPSLexer(startinline=True)
 
 
@@ -191,6 +192,7 @@ def setup(app):
 
 # URL redirects
 redirects = {
+    # outputs renamed to quantities
     "outputs/charges.html": "/quantities/charge.html",
     "outputs/energy.html": "/quantities/energy.html",
     "outputs/features.html": "/quantities/feature.html",
@@ -202,6 +204,13 @@ def setup(app):
     "outputs/positions.html": "/quantities/position.html",
     "outputs/variants.html": "/quantities/variants.html",
     "outputs/velocities.html": "/quantities/velocity.html",
+    # example re-organization
+    "examples/1-export-atomistic-model.html": "/examples/torch/1-export-atomistic-model.html",  # noqa: E501
+    "examples/2-running-ase-md.html": "/examples/ase/1-md.html",
+    "examples/3-atomistic-model-with-nl.html": "/examples/torch/2-atomistic-model-with-nl.html",  # noqa: E501
+    "examples/4-profiling.html": "/examples/torch/3-profiling.html",
+    "examples/5-torchsim-getting-started.html": "/examples/torchsim/1-getting-started.html",  # noqa: E501
+    "examples/6-torchsim-batched.html": "/examples/torchsim/2-batched-md.html",
 }
 
 # -- Options for HTML output -------------------------------------------------

docs/src/examples/index.rst

@@ -0,0 +1,80 @@
+.. _atomistic-tutorials:
+
+Tutorials
+=========
+
+The first set of tutorials on this page is about existing integrations between
+``metatomic`` and simulation engines. You can also find more example in the
+:ref:`engines` section. These tutorials are intended for users who want to use
+existing metatomic models with existing simulation engines.
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    ase/index
+    torchsim/index
+
+
+.. grid::
+
+    .. grid-item-card:: ASE tutorials
+        :link: ase-tutorials
+        :link-type: ref
+        :columns: 12 12 6 6
+        :margin: 0 3 0 0
+        :img-top: /../static/images/logo-ase.*
+        :class-img-top: mta-card-img-top
+
+        How to use ``metatomic`` with the Atomic Simulation Environment (ASE).
+
+    .. grid-item-card:: Torch-Sim tutorials
+        :link: torchsim-tutorials
+        :link-type: ref
+        :columns: 12 12 6 6
+        :margin: 0 3 0 0
+        :img-top: /../static/images/logo-radical-ai.*
+        :class-img-top: mta-card-img-top
+
+        How to use existing ``metatomic`` models with Torch-Sim, a simulation
+        engine for batched molecular dynamics simulations, based on PyTorch.
+
+
+--------------------------------------------------------------------------------
+
+The second set of tutorials on this page is intended for developers who want to
+use ``metatomic`` to either create new models, or run exising models in new
+simulation engine. These tutorials require existing knowledge of the
+corresponding programming languages and machine learning frameworks.
+
+.. toctree::
+    :maxdepth: 1
+    :hidden:
+
+    c/index
+    torch/index
+
+.. grid::
+
+    .. grid-item-card:: C API tutorials
+        :link: c-tutorials
+        :link-type: ref
+        :columns: 12 12 6 6
+        :margin: 0 3 0 0
+        :img-top: /../static/images/logo-c.*
+        :class-img-top: mta-card-img-top
+
+        How to use the C API of ``metatomic`` both to create custom atomistic
+        models; and to load and run existing atomistic models from simulation
+        engines.
+
+    .. grid-item-card:: PyTorch tutorials
+        :link: torch-tutorials
+        :link-type: ref
+        :columns: 12 12 6 6
+        :margin: 0 3 0 0
+        :img-top: /../static/images/logo-torch.*
+        :class-img-top: mta-card-img-top
+
+        How to use the PyTorch API of ``metatomic`` to define custom atomistic
+        models.

docs/static/css/metatomic.css

@@ -68,3 +68,10 @@ body[data-theme="auto"] {
 .font-size-small {
     font-size: small !important;
 }
+
+.mta-card-img-top {
+    width: 25% !important;
+    max-height: 25cqw;
+    margin: auto;
+    margin-top: 0.5em;
+}

examples/ase/README.rst

@@ -0,0 +1,4 @@
+.. _ase-tutorials:
+
+ASE tutorials
+=============