Improve README

Author: tovrstra

README.md

@@ -17,25 +17,25 @@ This module implements a 2D surface that resembles a curved slide, suitable for
 To give you a quick idea, the following figure is created with the [`plot.py`](plot.py) script in this repository,
 and visualizes the slides [`boxcar_blitz.toml`](boxcar_blitz.toml) and [`brutal_bends.toml`](brutal_bends.toml) included in this repository:
 
-![slides.jpg](slides.jpg)
+![slides.jpg](https://raw.githubusercontent.com/molmod/soapboxslide/main/slides.jpg)
 
 Your eyes may need some time to adapt to the correct depth perception: black ridges are high-altitude separations between the colored valleys.
 
 ## Concept
 
-The overall idea is that students use the surface implemented in `soapboxslide` to simulate the dynamics of a particle (or a connected set of particles) sliding down.
-In addition to correctly implementing the dynamics, an additional challenge is do so as quickly as possible without missing any of the waypoints shown as dotted circles.
+The idea is for students to use the surface implemented in `soapboxslide` to simulate the dynamics of a particle (or a connected set of particles) sliding down.
+In addition to correctly implementing the dynamics, students must do so as quickly as possible without missing any of the waypoints shown as dotted circles.
 
 Two classes of physical models can be considered:
 
 1. The most convenient is to assume a model of point particles strictly bound to the surface with holonomic constraints.
 In this case, equations of motion can be derived using a Lagrangian, possibly with a generalized force to include non-conservative friction forces.
 
-2. A more challenging scenario (not used for Py4Sci, but closer in spirit to soap box races) is to impose inequality constraints, allow particles to detach from the surface.
+2. A more challenging scenario (not used for now, but closer in spirit to real soap box races) is to impose inequality constraints, allowing particles to detach from the surface.
 
 ## Slide Class Usage
 
-One can load a surface from a TOML file and calculate the altitude at a given point, e.g. x=5 and y=38, as follows:
+One can load a surface from a TOML file and calculate slide properties at a given point, e.g. $x=5$ and $y=38$, as follows:
 
 ```python
 import numpy as np
@@ -100,32 +100,58 @@ This will show three gradients, one for each row of `pos`:
  [-2.16704263 -2.9280058 ]]
 ```
 
+In addition, a `Slide` instance has the following attributes:
+
+- `width`: the width of the slide arena in meter.
+- `height`: the height of the slide arena in meter.
+- `waypoints`: A 2D NumPy array with three columns (and at least two rows)
+  defining the shape and altitude of the slide track.
+  These are also intended as points that must be visited by a particle or a system sliding down,
+  to ensure that it followed a legitimate trajectory.
+- `target_radius`: a required proximity between a particle (or the center of mass of a system of particles) to a waypoint, to mark the waypoint as properly visited.
+  The distance is only measured in the $xy$-plane.
+
+Note that the above surface plots show dashed circles centered on the waypoints, whose radius is the target radius.
+
 ## Storing and Sharing Trajectory Data
 
 The `soapboxslide` module also implements a `Trajectory` class for storing the results of a numerical integration of one or more particles sliding over the surface.
-This class performs an initial validation on your trajectory data upon construction features `to_npz` and `from_npz` methods with which trajectories can be saved to and loaded from files.
+This class performs an initial validation on your trajectory data upon construction.
+It also features `to_file` and `from_file` methods with which trajectories can be saved to and loaded from NPZ files.
 This is useful if you want to share your trajectory with someone, e.g. for review, and to implement separate computation and visualization scripts (or notebooks).
 
 To use the `Trajectory` class, create an instance as follows after completing the numerical integration of the equations of motion:
 
 ```python
 traj = Trajectory(
-    time=...,
-    mass=...,
-    gamma=...,
-    pos=...,
-    vel=...,
-    grad=...,
-    hess=...,
-    spring_idx=...,
-    spring_par=...,
-    end_state=...,
-    stop_time=...,
-    stop_pos=...,
-    stop_vel=...,
+    time=...,        # NDArray[float], shape = (ntime, )
+    mass=...,        # NDArray[float], shape = (npoint, )
+    gamma=...,       # NDArray[float], shape = (npoint, )
+    pos=...,         # NDArray[float], shape = (ntime, npoint, 3), (x, y and z coordinates)
+    vel=...,         # NDArray[float], shape = (ntime, npoint, 3), (x, y and z coordinates)
+    grad=...,        # NDArray[float], shape = (ntime, npoint, 2), (h_x and h_y derivatives)
+    hess=...,        # NDArray[float], shape = (ntime, npoint, 3), (h_xx, h_xy and h_yy derivatives)
+    spring_idx=...,  # NDArray[int], shape = (nspring, 2), (each row is a pair of point indexes)
+    spring_par=...,  # NDArray[float], shape = (nspring, 3), (force constant, rest length, damping coeff)
+    end_state=...,   # One of the EndState enumeration
+    stop_time=...,   # Optional, time that last target was reached
+    stop_pos=...,    # Optional, NDArray[float], shape = (npoint, 3), positions at stop time
+    stop_vel=...,    # Optional, NDArray[float], shape = (npoint, 3), velocities at stop time
 )
 traj.to_file("traj.npz")
 ```
 
 In this Python snippet, you need to replace all triple dots by arrays you defined or computed.
-The meaning of and requirements for all attributes can be found in the docstrings in [`soapboxslide.py`](soapboxslide.py).
+Some guidelines:
+
+- If there are no springs yet, use arrays with zero rows for the spring definitions.
+- If there is just one particle, several arrays will have a size 1 axis, i.e. `npoint=1`.
+- You can first store all fields in a dictionary, e.g. `data` and optionally add the `stop_*` fields to the dictionary. The trajectory is then created with `Trajectory(**data)`.
+- The EndState enumeration can be specified to indicate when the numerical integration has ended:
+  - `EndState.STOP`: last target was reached in time
+  - `EndState.CRASH`: the numerical integration failed (e.g. due to Inf or Nan results)
+  - `EndState.FAR`: the particle moved more than 5 m out of the arena
+  - `EndState.TIMEOUT`: the maximum time, e.g. 60 s, was reached
+- You will get a `TypeError` or `ValueError` when creating the trajectory if some of the data does not meet some basic requirements.
+
+The meaning of and requirements for all attributes is further elaborated in the docstrings in [`soapboxslide.py`](soapboxslide.py).