Quickstart and Basic usage example (#123)

* Add skeleton for basic usage example

* Add basic usage notebook

* Make example complete apart from ML model

* Move notebook to example

* update example

* Improve descriptions with more details

* Add quickstart

* start proofread

* Add more details on vesin

---------

Co-authored-by: Kevin Kazuki Huguenin-Dumittan <[email protected]>

README.rst

@@ -56,6 +56,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/index.rst

@@ -27,6 +27,7 @@ Overview
 
    about
    installation
+   examples/basic-usage
    examples/index
    references/index
    contributing

docs/src/installation.rst

@@ -1,3 +1,5 @@
+.. _userdoc-installation:
+
 .. include:: ../../README.rst
     :start-after: marker-installation
-    :end-before: marker-issues
+    :end-before: marker-quickstart

docs/src/references/potentials/potential.rst

@@ -1,7 +1,7 @@
 Potential
 #########
 
-.. autoclass:: torchpme.potentials.Potential
+.. autoclass:: torchpme.Potential
     :members:
 
 .. minigallery:: torchpme.Potential

docs/src/references/potentials/spline.rst

@@ -1,7 +1,7 @@
 SplinePotential
 ###############
 
-.. autoclass:: torchpme.potentials.SplinePotential
+.. autoclass:: torchpme.SplinePotential
     :members:
 
 .. minigallery:: torchpme.SplinePotential

docs/src/references/utils/prefactors.rst

@@ -3,8 +3,9 @@
 Prefactors
 ==========
 
-This module contains common *prefactors* for converting between Gaussian units and other
-unit systems.
+This module contains common ``prefactors`` for converting between Gaussian units and
+other unit systems that can be used to set a unit system when initializing a
+:ref:`calculator <calculators>`.
 
 Many scientific calculators and computational tools, such as ``torchpme``, are set to
 operate in Gaussian units by default, where the term :math:`1/(4 \pi \epsilon_0) = 1.0`,

examples/2-neighbor-lists-usage.py

@@ -70,9 +70,7 @@
 # We now slightly displace the atoms from their initial positions randomly based on a
 # Gaussian distribution with a width of 0.1 Å to create non-zero forces.
 
-rng = np.random.default_rng(42)
-displacement = rng.normal(loc=0.0, scale=0.1, size=(len(atoms), 3))
-atoms.positions += displacement
+atoms.rattle(stdev=0.1)
 
 chemiscope.show(
     frames=[atoms],