Add a migration guide

CHANGELOG.md

@@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+The main changes of this release include support for Monte Carlo algorithms and performance improvements.
+
 ### Added
 
 - The `ForceField` object has a new method `compute` that can selectively compute

README.md

@@ -35,6 +35,14 @@ you can install TinyFF with:
 pip install tinyff
 ```
 
+## Migration from older versions
+
+Code written for TinyFF 1 can be easily updated to work with TinyFF 2.
+All required changes are documented in the [Migration Guide](migration.md).
+
+A complete list of changes is documented in [CHANGELOG.md](CHANGELOG.md).
+
+
 ## Features
 
 TinyFF is a Python package with the following modules:
@@ -244,8 +252,3 @@ atpos[iatom] += delta
 energy1, = ff.compute(atpos, cell_length)
 assert abs(energy_change - (energy1 - energy0)) < 1e-10
 ```
-
-
-## Change log
-
-The history of changes can be found in [CHANGELOG.md](CHANGELOG.md).

migration.md

@@ -0,0 +1,75 @@
+# Migration Guide
+
+This document lists changes you need to make when upgrading to a new version of TinyFF.
+Minor versions upgrades should maintain backward compatibility.
+Only when the major version changes, you may need to make changes to code using TinyFF
+
+
+## Upgrading from TinyFF 1.x to 2.x
+
+The required changes are relatively minor:
+
+- You can import all the relevant functions and classes from the top-level `tinyff` package.
+  For example, change from:
+
+    ```python
+    from tinyff.atomsmithy import build_fcc_lattice
+    from tinyff.forcefield import CutOffWrapper, LennardJones, ForceField
+    from tinyff.neighborlist import NBuildSimple
+    ```
+
+    to
+
+    ```python
+    from tinyff import build_fcc_lattice, CutOffWrapper, LennardJones, ForceField, NBuildSimple
+    ```
+
+    Note that the old `tinyff.forcefield` has been split into two modules: `forcefield` and `pairwise`.
+    By using the top-level imports, your code becomes independent of such internal details.
+
+- When creating a `ForceField` instance, the `nbuild` argument must be specified with a keyword.
+  For example, change from:
+
+    ```python
+    ff = ForceField([LennardJones(1.0, 1.0)], NBuildSimple(rmax))
+    ```
+
+    to
+
+    ```python
+    ff = ForceField([LennardJones(1.0, 1.0)], nbuild=NBuildSimple(rmax))
+    ```
+
+- When computing energies (and forces), you need to call the `ff.compute` method,
+  instead of using the force field object as a function.
+  If you want to compute forces and pressure, this must be requested explicitly.
+  By default, version 2 will only compute the energy.
+  For example, change from:
+
+    ```python
+    energy, forces, pressure = ff(atpos, cell_lengths)
+    ```
+
+    to
+
+    ```python
+    energy, forces, pressure = ff.compute(atpos, cell_lengths, nderiv=1)
+    ```
+
+- The pair potentials have undergone a similar change.
+  If you want to calculate the derivative, you need to ask for it explicitly.
+  By default, only the energy is computed.
+  (They are now all derived from `PairwiseTerm` instead of `PairPotential`)
+  For example, change from:
+
+    ```python
+    lj = LennardJones(1.0, 1.0)
+    e, g = lj.compute(dist)
+    ```
+
+    to
+
+    ```python
+    lj = LennardJones(1.0, 1.0)
+    e, g = lj.compute(dist, nderiv=1)
+    ```