✨ outputs: Annotate fields with Unit markers

`dough` 0.4 introduced the `Unit(...)` annotation on `Annotated[T, Spec(...),
Unit(...)]` to label a field's physical unit, and a matching `to="pint"` target
on `BaseOutput.get_output` / `get_output_dict` that wraps marked numeric outputs
into `pint.Quantity`. Annotate the existing `_PwMapping`,
`_PwParametersMapping`, and `_DosMapping` fields with their physical unit so
users can opt in to `pint`-based conversion (`pw_out.get_output("total_energy",
to="pint")`).

Units annotated:

- `_PwMapping`: `forces` (eV/Å), `stress` (GPa),
  `fermi_energy`/`fermi_energy_up`/ `fermi_energy_down`/`total_energy` (eV),
  `k_points_cartesian` (1/Å).
- `_PwParametersMapping`: `ecutwfc`, `ecutrho`, `degauss` (eV).
- `_DosMapping`: `energy`, `fermi_energy` (eV); `dos`, `dos_up`, `dos_down`
  (1/eV).

Fields without a meaningful physical unit (`integrated_dos` is a count of
states, `k_points_weights` are dimensionless QE-convention weights) deliberately
stay unmarked — `to="pint"` passes those through unchanged.

Also fix the `_DosMapping.integrated_dos` docstring to clarify the unit (number
of states, not eV).

Author: mbercx

pyproject.toml

@@ -30,7 +30,7 @@ dependencies = [
     'packaging',
     'xmlschema',
     'glom~=24.11',
-    'dough==0.3.0',
+    'dough==0.4.0',
 ]
 
 [project.urls]
@@ -40,14 +40,16 @@ Source = 'https://github.com/aiidateam/qe-tools'
 [project.optional-dependencies]
 ase = [
   "ase",
-  "pint"
 ]
 pymatgen = [
   "pymatgen"
 ]
 aiida = [
   "aiida-core"
 ]
+pint = [
+  "dough[pint]",
+]
 docs = [
 "mkdocs",
   "mkdocs-material"

src/qe_tools/outputs/dos.py

@@ -6,6 +6,7 @@
 
 from glom import Spec
 
+from dough import Unit
 from dough.converters import BaseConverter
 from dough.outputs import BaseOutput, output_mapping
 
@@ -32,23 +33,23 @@ def _determine_spin_type(spin: dict) -> str:
 class _DosMapping:
     """Typed outputs of a dos.x calculation."""
 
-    energy: Annotated[list, Spec("dos.energy")]
+    energy: Annotated[list, Spec("dos.energy"), Unit("eV")]
     """Energy grid in eV."""
 
-    dos: Annotated[list, Spec("dos.dos")]
+    dos: Annotated[list, Spec("dos.dos"), Unit("1/eV")]
     """Total density of states (states/eV). Not available for spin-polarised calculations."""
 
-    dos_up: Annotated[list, Spec("dos.dos_up")]
+    dos_up: Annotated[list, Spec("dos.dos_up"), Unit("1/eV")]
     """Spin-up DOS (states/eV). Not available for non-spin-polarised calculations."""
 
-    dos_down: Annotated[list, Spec("dos.dos_down")]
+    dos_down: Annotated[list, Spec("dos.dos_down"), Unit("1/eV")]
     """Spin-down DOS (states/eV). Not available for non-spin-polarised calculations."""
 
-    fermi_energy: Annotated[float, Spec("dos.fermi_energy")]
+    fermi_energy: Annotated[float, Spec("dos.fermi_energy"), Unit("eV")]
     """Fermi energy in eV."""
 
     integrated_dos: Annotated[list, Spec("dos.integrated_dos")]
-    """Integrated DOS."""
+    """Integrated DOS (# of states)."""
 
     full_dos: Annotated[dict, Spec("dos")]
     """Full parsed DOS dictionary."""

src/qe_tools/outputs/pw.py

@@ -7,6 +7,7 @@
 
 from glom import Coalesce, Spec
 
+from dough import Unit
 from dough.converters import BaseConverter
 from dough.outputs import BaseOutput, output_mapping
 
@@ -35,6 +36,7 @@ class _PwParametersMapping:
                 lambda ecut: ecut * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Kinetic-energy cutoff for wavefunctions in eV."""
 
@@ -46,6 +48,7 @@ class _PwParametersMapping:
                 lambda ecut: ecut * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Kinetic-energy cutoff for the charge density and potential in eV."""
 
@@ -107,6 +110,7 @@ class _PwParametersMapping:
                 lambda d: d * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Smearing width in eV."""
 
@@ -185,6 +189,7 @@ class _PwMapping:
                 ],
             )
         ),
+        Unit("eV/angstrom"),
     ]
     """Forces on atoms in eV/Å, shape [n_atoms][3]."""
 
@@ -202,6 +207,7 @@ class _PwMapping:
                 ],
             )
         ),
+        Unit("GPa"),
     ]
     """Stress tensor in GPa, shape [3][3]."""
 
@@ -213,6 +219,7 @@ class _PwMapping:
                 lambda energy: energy * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Fermi energy in eV."""
 
@@ -224,6 +231,7 @@ class _PwMapping:
                 lambda energies: energies[0] * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Fermi energy of spin-up channel in eV.
 
@@ -238,6 +246,7 @@ class _PwMapping:
                 lambda energies: energies[1] * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Fermi energy of spin-down channel in eV.
 
@@ -278,6 +287,7 @@ class _PwMapping:
                 ],
             )
         ),
+        Unit("1/angstrom"),
     ]
     """Cartesian coordinates of the k-points in 1/Å, shape `[n_kpoints][3]`."""
 
@@ -300,6 +310,7 @@ class _PwMapping:
                 lambda energy: energy * CONSTANTS.hartree_to_ev,
             )
         ),
+        Unit("eV"),
     ]
     """Total energy in eV."""