Add deprecation warning when using opmd_viewer, and update CHANGELOG

CHANGELOG.md

@@ -2,12 +2,28 @@
 
 ## 1.0
 
-This version introduces a capability to do slicing along several directions,
-and for 1d, 2d, 3d and circ geometries.
-It breaks backward compatibility: for a 3d field,
+This version introduces major changes and breaks backward compatibility.
+
+Here is a list of the changes:
+- The import statement now uses `openpmd_viewer` instead of `opmd_viewer`, e.g.
+```
+from openpmd_viewer import OpenPMDTimeSeries
+```
+- For consistency, `ts.get_particle` now return particle positions in meters,
+instead of microns. For instance, in the code below, `x`, `y`, `z` will be in
+meters
+```
+x, y, z = ts.get_particle(['x', 'y', 'z'], iteration=1000)
+```
+- In `ts.get_field`, slicing can now be done in several directions
+(by passing a list as the argument `slicing_dir`), and for
+1d, 2d, 3d, and circ geometries. As a consequence, this breaks backward
+compatibility for 3d field:
 ```get_field(field=field, coord=coord, iteration=iteration)```
-used to return the central slice along `y` while it returns the full 3d field
-now.
+used to return the central slice along `y` while it now returns the full 3d field.
+- A new function (`ts.iterate`) was introduced in order to quickly apply a
+given function to all iterations of a time series. See the docstring of
+`ts.iterate` for more information.
 
 ## 0.9.0
 

opmd_viewer/__init__.py

@@ -0,0 +1,29 @@
+"""
+This is a stub that detects whether the user is attempting to use the
+old import statement from openPMD-viewer 0.X (`import opmd_viewer`).
+
+In that case, an exception is raised that prompts the user to use the new API.
+"""
+# Define the version number
+from openpmd_viewer import __version__
+__all__ = ['__version__']
+
+raise DeprecationWarning("""
+It looks like you are trying to use the API from openPMD-viewer version 0.X
+but the installed version on your system is openPMD-viewer version 1.X.
+
+* If you wish to use the new openPMD-viewer version 1.X, the import statement
+should use `openpmd_viewer` instead of `opmd_viewer`, e.g.:
+```
+from openpmd_viewer import OpenPMDTimeSeries
+```
+Please have a look at the list of the changes introduced in version 1.X here:
+https://github.com/openPMD/openPMD-viewer/blob/upcoming-1.0/CHANGELOG.md#10
+In particular, note that `get_particle` now returns particle positions in
+meters (not in microns anymore).
+
+* If you wish to go back to the old openPMD-viewer version 0.X, use:
+```
+pip install openPMD-viewer==0.9
+```
+""")