Add quickstart

README.rst

@@ -50,6 +50,58 @@ can optionally be installed together and used as ``torchpme.metatensor`` via
 
     pip install torch-pme[metatensor]
 
+.. marker-quickstart
+
+Quickstart
+----------
+
+Here is a simple example get you started with *torch-pme*:
+
+.. code-block:: python
+
+   import torch
+   import torchpme
+
+   # Single charge in a cubic box
+   positions = torch.zeros((1, 3), requires_grad=True)
+   cell = 8 * torch.eye(3)
+   charges = torch.tensor([[1.0]])
+
+   # No neighbors for a single atom; use `vesin` for neighbors if needed
+   neighbor_indices = torch.zeros((0, 2), dtype=torch.int64)
+   neighbor_distances = torch.zeros((0,))
+
+   # Tune P3M parameters (cutoff optional, useful to set for ML with fixed cutoff)
+   smearing, p3m_parameters, _ = torchpme.utils.tune_p3m(
+      sum_squared_charges=1,
+      cell=cell,
+      positions=positions,
+      cutoff=5.0,
+   )
+
+   # Initialize potential and calculator
+   potential = torchpme.CoulombPotential(smearing)
+   calculator = torchpme.P3MCalculator(potential, **p3m_parameters)
+
+   # Compute (per-atom) potentials
+   potentials = calculator.forward(
+      charges=charges,
+      cell=cell,
+      positions=positions,
+      neighbor_indices=neighbor_indices,
+      neighbor_distances=neighbor_distances,
+   )
+
+   # Calculate total energy and forces
+   energy = torch.sum(charges * potentials)
+   energy.backward()
+   forces = -positions.grad
+
+   print("Energy:", energy.item())
+   print("Forces:", forces)
+
+For more examples and details, please refer to the `documentation`_.
+
 .. marker-issues
 
 Having problems or ideas?

docs/src/installation.rst

@@ -2,4 +2,4 @@
 
 .. include:: ../../README.rst
     :start-after: marker-installation
-    :end-before: marker-issues
+    :end-before: marker-quickstart

src/torchpme/calculators/calculator.py

@@ -233,7 +233,7 @@ def _validate_compute_parameters(
 
         if charges.dtype != dtype:
             raise ValueError(
-                f"type of `charges` ({cell.dtype}) must be same as `positions` "
+                f"type of `charges` ({charges.dtype}) must be same as `positions` "
                 f"({dtype})"
             )
 

tests/calculators/test_calculator.py

@@ -142,7 +142,7 @@ def test_invalid_shape_charges():
 def test_invalid_dtype_charges():
     calculator = CalculatorTest()
     match = (
-        r"type of `charges` \(torch.float32\) must be same as `positions` "
+        r"type of `charges` \(torch.float64\) must be same as `positions` "
         r"\(torch.float32\)"
     )
     with pytest.raises(ValueError, match=match):