Add an API to iterate over all timesteps

[RemiLehe]

As pointed out by @MaxThevenet and @soerenjalas, it is often useful to call openPMD-viewer methods for each timestep of a timeseries, and it would be nice to have an API that does this automatically. This would be useful for:

• Analyzing emittance, laser intensity, etc. as a function of time
• Reconstructing particle trajectories (see https://github.com/openPMD/openPMD-viewer/blob/master/tutorials/4_Particle_selection.ipynb)

[RemiLehe]

One relatively easy way of doing it would be to introduce e.g. a ts.iterate function:

• For the emittance

  ts.iterate( ts.get_emittance, species='electrons', select={'uz':[40, 100]} )

• For the laser a0

  ts.iterate( ts.get_a0, pol='x' )

• For particle tracking and reconstructing trajectory

  # Initial selection
  pt = ParticleTracker( ts, iteration=300, select={'uz':[0.05,0.1], 'z':[22,26]}, 
                       species='electrons', preserve_particle_index=True )
  # Reconstruct trajectories
  ts.iterate( ts.get_particles, select=pt )

In summary:

• The user would pass the method to be called, and then the arguments that would normally be passed to this function (except for t and iteration of course)
• ts.iterate would return a stacked array of the results (i.e. if the called method normally returns a scalar, then ts.iterate would return a 1darray ; if the called method normally returns a 1darray, then ts.iterate would return a 2darray). If the called method returns a tuple, than ts.iterate would return a tuple of stacked arrays.

[RemiLehe]

@soerenjalas @MaxThevenet: Any opinion, preference or better suggestions on the above?

From my point of view, here are the advantages and drawbacks:

Advantages:

• Easy to implement
• No code duplication

Drawbacks:

• As @soerenjalas pointed out, sometimes, select will change as a function of time. This is not supported in this case. However, if particle tracking is implemented, then we could select at only one time and use the ParticleTracker to always retrieve the same particles.
• The user is responsible for ensuring that, if arrays are returned by the called method, than their shape should be identical for each timestep. (Otherwise stacking them is not possible.)
• It is kind of annoying to have to type ts multiple times in a single call.

[soerenjalas]

This pretty much the exact thing I was thinking of. I think for now it is okay to have only one selection for the full loop. Maybe we come up with an elegant solution in the future.

For your second drawback: One could list append them (i.e. list of list), but this also has its own drawback. I don't have a strong opinion but I guess numpy arrays are nicer to handle.

[RemiLehe]

OK, thanks! If @MaxThevenet also agrees with this approach, then I can try to do a PR. I think I see more or less how to implement this.

[MaxThevenet]

Yep I agree with this approach. Doing it this way, we'll loop over all iterations once per method. If that is taking too much time for some analysis, we can probably adapt ts.iterate in the future, so that it takes several routines as @soerenjalas suggested initially, and does the loop only once.