Deprecate plural outputs, unify inputs and outputs

docs/src/conf.py

@@ -135,6 +135,7 @@ def setup(app):
     "myst_parser",
     "sphinx_design",
     "chemiscope.sphinx",
+    "sphinx_reredirects",
     # local extensions
     "versions_list",
 ]
@@ -183,6 +184,21 @@ def setup(app):
 sitemap_url_scheme = "{link}"  # avoids language settings
 html_extra_path = ["robots.txt"]  # extra files to move
 
+# URL redirects
+redirects = {
+    "outputs/charges.html": "/quantities/charge.html",
+    "outputs/energy.html": "/quantities/energy.html",
+    "outputs/features.html": "/quantities/feature.html",
+    "outputs/heat_flux.html": "/quantities/heat_flux.html",
+    "outputs/index.html": "/quantities/index.html",
+    "outputs/masses.html": "/quantities/mass.html",
+    "outputs/momenta.html": "/quantities/momentum.html",
+    "outputs/non_conservative.html": "/quantities/non_conservative.html",
+    "outputs/positions.html": "/quantities/position.html",
+    "outputs/variants.html": "/quantities/variants.html",
+    "outputs/velocities.html": "/quantities/velocity.html",
+}
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.

docs/src/engines/ase.rst

@@ -16,17 +16,15 @@ Supported model outputs
 
 .. py:currentmodule:: metatomic_ase
 
-- the :ref:`energy <energy-output>`, non-conservative :ref:`forces
-  <non-conservative-forces-output>` and :ref:`stress <non-conservative-stress-output>`
-  including their :ref:`variants <output-variants>` are supported and fully integrated
-  with ASE calculator interface (i.e. :py:meth:`ase.Atoms.get_potential_energy`,
+- the :ref:`energy <energy-quantity>`, non-conservative :ref:`forces
+  <non-conservative-force-quantity>` and :ref:`stress
+  <non-conservative-stress-quantity>` including their :ref:`variants
+  <quantity-variants>` are supported and fully integrated with ASE calculator
+  interface (i.e. :py:meth:`ase.Atoms.get_potential_energy`,
   :py:meth:`ase.Atoms.get_forces`, …);
 - arbitrary outputs can be computed for any :py:class:`ase.Atoms` using
   :py:meth:`MetatomicCalculator.run_model`;
-- for non-equivariant architectures like
-  `PET <https://docs.metatensor.org/metatrain/latest/architectures/pet.html>`_,
-  rotationally-averaged energies, forces, and stresses can be computed using
-  :py:class:`metatomic_ase.SymmetrizedCalculator`.
+
 
 How to install the code
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/src/engines/chemiscope.rst

@@ -14,7 +14,7 @@ chemiscope
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The :ref:`features <features-output>` output is supported, and can be used to
+The :ref:`feature <feature-quantity>` quantity is supported, and can be used to
 compute features for multiple structures in ``chemiscope.explore()``.
 
 How to install the code

docs/src/engines/eon.rst

@@ -15,13 +15,13 @@ eOn
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The eOn interface primarily utilizes the :ref:`energy <energy-output>` output to
-compute forces via autograd and drive molecular dynamics or saddle point
-searches.
+The eOn interface primarily utilizes the :ref:`energy <energy-quantity>`
+quantity to compute forces via autograd and drive molecular dynamics or saddle
+point searches.
 
 Additionally, the interface supports the :ref:`energy_uncertainty
-<energy-uncertainty-output>` output. When enabled, the client checks per-atom
-uncertainties against a user-defined threshold and flags or terminates
+<energy-uncertainty-quantity>` quantity. When enabled, the client checks
+per-atom uncertainties against a user-defined threshold and flags or terminates
 calculations that enter unreliable regions of the potential energy surface.
 
 This allows running methods including:

docs/src/engines/gromacs.rst

@@ -14,9 +14,10 @@ GROMACS
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The :ref:`energy <energy-output>` is supported in the custom metatomic module in
-GROMACS. The module allows running molecular dynamics simulations on the full system or
-on a subgroup (ML/MM) with interatomic potentials in the metatomic format.
+The :ref:`energy <energy-quantity>` is supported in the custom metatomic module
+in GROMACS. The module allows running molecular dynamics simulations on the full
+system or on a subgroup (ML/MM) with interatomic potentials in the metatomic
+format.
 
 How to install the code
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/src/engines/ipi.rst

@@ -15,10 +15,11 @@ i-PI
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The :ref:`energy <energy-output>`, non-conservative :ref:`forces
-<non-conservative-forces-output>` and :ref:`stress <non-conservative-stress-output>`
-outputs are supported, and can be used to run path integral simulations, incorporating
-integral simulations, incorporating quantum nuclear effects in the statistical sampling.
+The :ref:`energy <energy-quantity>`, non-conservative :ref:`forces
+<non-conservative-force-quantity>` and :ref:`stress
+<non-conservative-stress-quantity>` outputs are supported, and can be used to
+run path integral simulations, incorporating quantum nuclear effects in the
+statistical sampling.
 
 How to install the code
 ^^^^^^^^^^^^^^^^^^^^^^^

docs/src/engines/lammps.rst

@@ -15,11 +15,12 @@ LAMMPS
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The :ref:`energy <energy-output>`, non-conservative :ref:`forces
-<non-conservative-forces-output>` and :ref:`stress <non-conservative-stress-output>`
-outputs are supported in LAMMPS, as a custom ``pair_style``. This allows running
-molecular dynamics simulations with interatomic potentials in the metatomic format;
-distributing the simulation over multiple nodes and potentially multiple GPUs.
+The :ref:`energy <energy-quantity>`, non-conservative :ref:`forces
+<non-conservative-force-quantity>` and :ref:`stress
+<non-conservative-stress-quantity>` outputs are supported in LAMMPS, as a custom
+``pair_style``. This allows running molecular dynamics simulations with
+interatomic potentials in the metatomic format; distributing the simulation over
+multiple nodes and potentially multiple GPUs.
 
 How to install the code
 ^^^^^^^^^^^^^^^^^^^^^^^
@@ -313,7 +314,7 @@ documentation.
         set this to on/off to enable/disable internal consistency checks, verifying both
         the data passed by LAMMPS to the model, and the data returned by the model to
         LAMMPS.
-      **uncertainty_threshold** values = float or off  
+      **uncertainty_threshold** values = float or off
         sets a threshold on the maximum allowed energy uncertainty for the model
         predictions. If the model returns an uncertainty larger than this threshold for
         any of the atoms in the system, the simulation will issue a warning. Default to

docs/src/engines/plumed-model.py

@@ -22,10 +22,10 @@ def forward(
         outputs: Dict[str, mta.ModelOutput],
         selected_atoms: Optional[mts.Labels],
     ) -> Dict[str, mts.TensorMap]:
-        if "features" not in outputs:
+        if "feature" not in outputs:
             return {}
 
-        if outputs["features"].sample_kind == "atom":
+        if outputs["feature"].sample_kind == "atom":
             raise ValueError("per-atoms features are not supported in this model")
 
         # PLUMED will first call the model with 0 atoms to get the size of the
@@ -43,7 +43,7 @@ def forward(
                 ),
             )
 
-            return {"features": mts.TensorMap(keys, [block])}
+            return {"feature": mts.TensorMap(keys, [block])}
 
         if selected_atoms is None:
             raise ValueError("this model requires selected_atoms to be set")
@@ -79,7 +79,7 @@ def forward(
             properties=mts.Labels("distance", torch.zeros((1, 1), dtype=torch.int32)),
         )
 
-        return {"features": mts.TensorMap(keys, [block])}
+        return {"feature": mts.TensorMap(keys, [block])}
 
 
 # instantiates the model, describes its metadata, and export
@@ -94,7 +94,7 @@ def forward(
 # metatdata about what the model can do
 capabilities = mta.ModelCapabilities(
     length_unit="Angstrom",
-    outputs={"features": mta.ModelOutput(sample_kind="system")},
+    outputs={"feature": mta.ModelOutput(sample_kind="system")},
     atomic_types=[0],
     interaction_range=torch.inf,
     supported_devices=["cpu", "cuda"],

docs/src/engines/plumed.rst

@@ -29,7 +29,7 @@ See the official `installation instructions`_ in the documentation of PLUMED.
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The model must provide a :ref:`features <features-output>` output, and it is
+The model must provide a :ref:`feature <feature-quantity>` output, and it is
 important that this output has a fixed size, and that the size can be determined
 by executing the model with an empty system (as this is how PLUMED determines
 internally the size of a CV). A minimal example of a model that computes the

docs/src/engines/torch-sim.rst

@@ -25,7 +25,7 @@ For the full TorchSim documentation, see https://torchsim.github.io/torch-sim/.
 Supported model outputs
 ^^^^^^^^^^^^^^^^^^^^^^^
 
-The :ref:`energy <energy-output>` output is the primary output. Forces and
+The :ref:`energy <energy-quantity>` output is the primary output. Forces and
 stresses are derived via autograd by default. The wrapper also supports:
 
 - **Non-conservative forces/stress**: use direct prediction of gradients instead

docs/src/index.rst

@@ -42,14 +42,15 @@ existing trained models, look into the metatrain_ project instead.
         Learn how to define your own models using ``metatomic``, and how to use
         these models to run calculations in various engines.
 
-    .. grid-item-card:: 📋 Standard models outputs
-        :link: atomistic-models-outputs
+    .. grid-item-card:: 📋 Standard quantities
+        :link: standard-quantities
         :link-type: ref
         :columns: 12 12 6 6
         :margin: 0 3 0 0
 
-        Understand the different outputs a model can have, and what the metadata
-        should be provided for standardized outputs, such as the potential energy.
+        Understand the different standardized quantities that are defined in
+        ``metatomic``, and how to use them as inputs and outputs of your models
+        to ensure maximum compatibility with different simulation engines.
 
     .. grid-item-card:: ⚙️ Simulation engines
         :link: engines
@@ -92,7 +93,7 @@ existing trained models, look into the metatrain_ project instead.
     overview
     installation
     torch/index
-    outputs/index
+    quantities/index
     engines/index
     examples/index
     cite