Generic interface: OpenPMDTimeSeries

class openpmd_viewer.OpenPMDTimeSeries(path_to_dir, check_all_files=True, backend=None)[source]

Initialize an openPMD time series

More precisely, scan the directory and extract the openPMD files, as well as some useful openPMD parameters

Parameters:

  • path_to_dir (string) – The path to the directory where the openPMD files are.

  • check_all_files (bool, optional) – Check that all the files in the timeseries are consistent (i.e. that they contain the same fields and particles, with the same metadata) For fast access to the files, this can be changed to False.

  • backend (string) – Backend to be used for data reading. Can be openpmd-api or h5py. If not provided will use openpmd-api if available and h5py otherwise.

get_field(field=None, coord=None, t=None, iteration=None, m='all', theta=0.0, slice_across=None, slice_relative_position=None, plot=False, plot_range=[[None, None], [None, None]], **kw)[source]

Extract a given field from a file in the openPMD format.

Parameters:

  • field (string, optional) – Which field to extract

  • coord (string, optional) – Which component of the field to extract

  • m (int or str, optional) – Only used for thetaMode geometry Either ‘all’ (for the sum of all the modes) or an integer (for the selection of a particular mode)

  • t (float (in seconds), optional) – Time at which to obtain the data (if this does not correspond to an existing iteration, the closest existing iteration will be used) Either t or iteration should be given by the user.

  • iteration (int) – The iteration at which to obtain the data Either t or iteration should be given by the user.

  • theta (float or None, optional) – Only used for thetaMode geometry The angle of the plane of observation, with respect to the x axis If theta is not None, then this function returns a 2D array corresponding to the plane of observation given by theta ; otherwise it returns a full 3D Cartesian array

  • slice_across (str or list of str, optional) –

    Direction(s) across which the data should be sliced + In cartesian geometry, elements can be:

    • 1d: ‘z’

    • 2d: ‘x’ and/or ‘z’

    • 3d: ‘x’ and/or ‘y’ and/or ‘z’

    • In cylindrical geometry, elements can be ‘r’ and/or ‘z’

    Returned array is reduced by 1 dimension per slicing. If slicing is None, the full grid is returned.

  • slice_relative_position (float or list of float, optional) – Number(s) between -1 and 1 that indicate where to slice the data, along the directions in slice_across -1 : lower edge of the simulation box 0 : middle of the simulation box 1 : upper edge of the simulation box Default: None, which results in slicing at 0 in all direction of slice_across.

  • plot (bool, optional) – Whether to plot the requested quantity

  • plot_range (list of lists) – A list containing 2 lists of 2 elements each Indicates the values between which to clip the plot, along the 1st axis (first list) and 2nd axis (second list) Default: plots the full extent of the simulation box

  • **kw (dict, otional) – Additional options to be passed to matplotlib’s imshow.

Returns:

F : a 2darray containing the required field info : a FieldMetaInformation object (see the corresponding docstring)

Return type:

A tuple with

get_particle(var_list=None, species=None, t=None, iteration=None, select=None, plot=False, nbins=150, plot_range=[[None, None], [None, None]], use_field_mesh=True, histogram_deposition='cic', **kw)[source]

Extract a list of particle variables an openPMD file.

Plot the histogram of the returned quantity. If two quantities are requested by the user, this plots a 2d histogram of these quantities.

In the case of momenta, the result is returned as: - unitless momentum (i.e. gamma*beta) for particles with non-zero mass - in kg.m.s^-1 for particles with zero mass

Parameters:

  • var_list (list of string, optional) – A list of the particle variables to extract. If var_list is not provided, the available particle quantities are printed

  • species (string) – A string indicating the name of the species This is optional if there is only one species

  • t (float (in seconds), optional) – Time at which to obtain the data (if this does not correspond to an existing iteration, the closest existing iteration will be used) Either t or iteration should be given by the user.

  • iteration (int) – The iteration at which to obtain the data Either t or iteration should be given by the user.

  • select (dict or ParticleTracker object, optional) –

    • If select is a dictionary:

    then it lists a set of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘ux’ : [-0.1, 0.1] (Particles having ux between -0.1 and 0.1 mc) ‘uz’ : [5., None] (Particles with uz above 5 mc) - If select is a ParticleTracker object: then it returns particles that have been selected at another iteration ; see the docstring of ParticleTracker for more info.

  • plot (bool, optional) – Whether to plot the requested quantity Plotting support is only available when requesting one or two quantities (i.e. when var_list is of length 1 or 2)

  • nbins (int, optional) – (Only used when plot is True) Number of bins for the histograms

  • plot_range (list of lists) – A list containing 2 lists of 2 elements each Indicates the values between which to perform the histogram, along the 1st axis (first list) and 2nd axis (second list) Default: the range is automatically determined

  • use_field_mesh (bool, optional) –

    (Only used when plot is True) Whether to use the information of the spatial mesh (whenever possible) in order to choose the parameters of the histograms. More precisely, when this is True: - The extent of the histogram (along any spatial dimension) is

    automatically chosen to be roughly the extent of the spatial mesh.

    • The number of bins (along any spatial dimension) is slightly modified (from the value nbins provided by the user) so that the spacing of the histogram is an integer multiple of the grid spacing. This avoids artifacts in the plot, whenever particles are regularly spaced in each cell of the spatial mesh.

  • histogram_deposition (string) – Either ngp (Nearest Grid Point) or cic (Cloud-In-Cell) When plotting the particle histogram, this determines how particles affects neighboring bins. cic (which is the default) leads to smoother results than ngp.

  • **kw (dict, otional) – Additional options to be passed to matplotlib’s hist or hist2d.

Returns:

  • A list of 1darray corresponding to the data requested in var_list

  • (one 1darray per element of ‘var_list’, returned in the same order)

iterate(called_method, *args, **kwargs)[source]

Repeated calls the method called_method for every iteration of this timeseries, with the arguments *args and *kwargs.

The result of these calls is returned as a list, or, whenever possible as an array, where the first axis corresponds to the iterations.

If called_method returns a tuple/list, then iterate returns a tuple/list of lists (or arrays).

Parameters:

  • *args (arguments and keyword arguments) – Arguments that would normally be passed to called_method for a single iteration. Do not pass the argument t or iteration.

  • **kwargs (arguments and keyword arguments) – Arguments that would normally be passed to called_method for a single iteration. Do not pass the argument t or iteration.

slider(figsize=(6, 5), fields_figure=0, particles_figure=1, exclude_particle_records=['charge', 'mass'], **kw)

Navigate the simulation using a slider

Parameters:

  • figsize (tuple) – Size of the figures

  • fields_figure (ints) – The number of the matplotlib figure on which the fields and the particles will be plotted respectively. (This is similar to calling plt.figure(fields_figure))

  • particle_figure (ints) – The number of the matplotlib figure on which the fields and the particles will be plotted respectively. (This is similar to calling plt.figure(fields_figure))

  • exclude_particle_records (list of strings) – List of particle quantities that should not be displayed in the slider (typically because they are less interesting)

  • kw (dict) – Extra arguments to pass to matplotlib’s imshow (e.g. cmap, etc.). This will be applied both to the particle plots and field plots. Note that kw sets the initial plotting options, but the user can then still modify these options through the slider interface.