Domain-specific interface: LpaDiagnostics

class openpmd_viewer.addons.LpaDiagnostics(path_to_dir, check_all_files=True, backend=None)

Initialize an OpenPMD time series with various methods to diagnose the data

Parameters:

• path_to_dir (string) – The path to the directory where the openPMD files are. For the moment, only HDF5 files are supported. There should be one file per iteration, and the name of the files should end with the iteration number, followed by ‘.h5’ (e.g. data0005000.h5)

• 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_energy_spread(t=None, iteration=None, species=None, select=None, center='mean', width='std', property='energy')

Calculate the central energy and energy spread according to the particle weights

Parameters:

• 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.

• species (str) – Particle species to use for calculations

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters)

• center (str) –

  Method to find the central energy of the particle distribution Should be one of

  • ’mean’

  • ’median’

• width (str) –

  Method to find the energy spread of the particle distribution Should be one of

  • ’std’

  • ’mad’

• property (str) –

  Unit of energy. Should be one of

  • ’energy’ returns energy in MeV

  • ’gamma’ returns Lorentz factor

Returns:

• A tuple of floats with

• - central energy

• - energy spread

• Returns NaN if particle selection is empty

get_mean_gamma(t=None, iteration=None, species=None, select=None)

Calculate the mean gamma and standard deviation according to the particle weights

Parameters:

• 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.

• species (string) – Particle species to use for calculations

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters)

Returns:

• A tuple of floats with

• - mean weighted gamma

• - weighted standard deviation of gamma

• Returns NaN if particle selection is empty

get_sigma_gamma_slice(dz, t=None, iteration=None, species=None, select=None, plot=False, **kw)

Calculate the standard deviation of gamma for particles in z-slices of width dz

Parameters:

• dz (float (in micrometers)) – Width of slices in which to calculate sigma gamma

• 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.

• species (string) – Particle species to use for calculations

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters)

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

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

Returns:

• A tuple of arrays

• - Sigma gamma in each slice

• - Central z position of each slice

get_charge(t=None, iteration=None, species=None, select=None)

Calculate the charge of the selcted particles.

Parameters:

• 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.

• species (string) – Particle species to use for calculations

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters)

Return type:

A float with the electric charge of the selected particles in Coulomb

get_divergence(t=None, iteration=None, species=None, select=None)

Calculate the divergence of the selected particles.

Parameters:

• 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.

• species (string) – Particle species to use for calculations

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters)

Returns:

• A tuple with

• - divergence in x plane in rad

• - divergence in y plane in rad

• Returns NaN if particle selection is empty

get_emittance(t=None, iteration=None, species=None, select=None, kind='normalized', description='projected', nslices=0, beam_length=None)

Calculate the RMS emittance. (See K Floetmann: Some basic features of beam emittance. PRSTAB 2003)

Parameters:

• 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.

• species (string) – Particle species to use for calculations

• select (dict, optional) – Either None or a dictionary of rules to select the particles, of the form: ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters).

• kind (string, optional) – Kind of emittance to be computed. Can be ‘normalized’ or ‘trace’.

• description (string, optional) –

  Type of emittance to be computed. Available options:

  • ’projected’ : projected emittance

  • ’all-slices’emittance within slices taken along the z

    direction

  • ’slice-averaged’ : slice emittance averaged over all slices.

• nslices (integer, optional) – Number of slices to compute slice emittance. Required if description=’slice-average’ or ‘all-slices’.

• beam_length (float (in meters), optional) – Beam length, used to calculate slice positions when nslices>1. By default, it is 4 times the standard deviation in z.

Returns:

• If description=’projected’ or ‘slice-averaged’ –

  • beam emittance in the x plane (pi m rad)

  • beam emittance in the y plane (pi m rad)

• If description=’all-slices’ –

  • A 1d array with beam emittance in the x plane (pi m rad) for each slice

  • A 1d array with beam emittance in the y plane (pi m rad) for each slice

  • A 1d array with number of electrons in each slice

  • A 1d array with slice centers

get_current(t=None, iteration=None, species=None, select=None, bins=100, plot=False, **kw)

Calculate the electric current along the z-axis for selected particles.

Parameters:

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

iterationint

The iteration at which to obtain the data Either t or iteration should be given by the user

speciesstring

Particle species to use for calculations

selectdict, optional

Either None or a dictionary of rules to select the particles, of the form ‘x’ : [-4., 10.] (Particles having x between -4 and 10 meters) ‘z’ : [0, 100] (Particles having z between 0 and 100 meters)

binsint, optional

Number of bins along the z-axis in which to calculate the current

plotbool, optional

Whether to plot the requested quantity

**kwdict, otional

Additional options to be passed to matplotlib’s plot method

Returns:

• A tuple of arrays containig

• - The current in each bin in Ampere

• - A FieldMetaInformation object – (see object’s docstring for more details)

get_laser_envelope(t=None, iteration=None, pol=None, laser_propagation='z', m='all', theta=0, slice_across=None, slice_relative_position=None, plot=False, plot_range=[[None, None], [None, None]], **kw)

Calculate a laser field by filtering out high frequencies. Can either return the envelope slice-wise or a full 2D envelope.

Parameters:

• 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.

• pol (string) – Polarization of the field. Options are ‘x’, ‘y’, ‘z’

• laser_propagation (string, optional) – Coordinate along which laser field propagates. Default is ‘z’.

• 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)

• theta (float, optional) – Only used for thetaMode geometry The angle of the plane of observation, with respect to the x axis

• 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 slice_across is None, the full grid is returned. Default is None.

• 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 is 0.

• 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 plot`(1D) or `imshow (2D) method

Returns:

• A tuple with

• - Envelope data (1D or 2D array)

• - A FieldMetaInformation object

get_main_frequency(t=None, iteration=None, pol=None, m='all', method='max')

Calculate the angular frequency of a laser pulse.

Parameters:

• 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.

• pol (string) – Polarization of the field. Options are ‘x’, ‘y’

• 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)

• method (string, optional) – Method which is used to calculate the frequency of the pulse ‘fit’ : Fit a Gaussian curve to find central frequency ‘max’ : Take frequency with highest intensity in the spectrum

Return type:

A float with mean angular frequency

get_spectrum(t=None, iteration=None, pol=None, m='all', plot=False, **kw)

Return the spectrum of the laser (Absolute value of the Fourier transform of the fields.)

Parameters:

• 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.

• pol (string) – Polarization of the field. Options are ‘x’, ‘y’

• 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)

• plot (bool, optional) – Whether to plot the data

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

Returns:

• The 1D spectrum on axis

• A FieldMetaInformation object

Return type:

A tuple with

get_a0(t=None, iteration=None, pol=None)

Gives the laser strength a0 given by a0 = Emax * e / (me * c * omega)

Parameters:

• 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.

• pol (string) – Polarization of the field. Options are ‘x’, ‘y’

Return type:

Float with normalized vector potential a0

get_ctau(t=None, iteration=None, pol=None, method='fit')

Calculate the length of a (gaussian) laser pulse. Here ‘length’ means the ‘longitudinal waist’ (i.e sqrt(2) * sigma_z).

Parameters:

• 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.

• pol (string) – Polarization of the field. Options are ‘x’, ‘y’

• method (str, optional) – The method which is used to compute ctau ‘fit’: Gaussian fit of the longitudinal profile ‘rms’: RMS radius, weighted by the longitudinal profile (‘rms’ tends to give more weight to the “wings” of the pulse)

Return type:

Float with ctau in meters

get_laser_waist(t=None, iteration=None, pol=None, theta=0, laser_propagation='z', method='fit', profile_method='peak')

Calculate the waist of a (gaussian) laser pulse. ( sqrt(2) * sigma_r)

In 3D, this function takes a slice across y, and thus computes the waist in the x-z plane.

Parameters:

• 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.

• pol (string) – Polarization of the field. Options are ‘x’, ‘y’

• theta (float, optional) – Only used for thetaMode geometry The angle of the plane of observation, with respect to the x axis

• laser_propagation (string, optional) – Coordinate along which laser field propagates. Default is ‘z’.

• method (str, optional) – The method which is used to compute the waist ‘fit’: Gaussian fit of the transverse profile ‘rms’: RMS radius, weighted by the transverse profile (‘rms’ tends to give more weight to the “wings” of the pulse)

• profile_method (str, optional, default 'peak') – Method used to obtain the transverse profile. Options are: ‘peak’,’projection’

Return type:

Float with laser waist in meters

get_spectrogram(t=None, iteration=None, pol=None, plot=False, **kw)

Calculates the spectrogram of a laserpulse, by the FROG method.

Mathematically: $$ s(omega, au) = | int_{-infty}^{infty} E(t) |E(t- au)|^2

exp( -iomega t) dt |^2 $$

See Trebino, R: Frequency Resolved Optical Gating: The measurements of Ultrashort Laser Pulses: year 2000: formula 5.2

The time is centered around the laser pulse.

Parameters:

• 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.

• pol (string) – Polarization of the laser field. Options are ‘x’, ‘y’

• plot (bool, optional) – Whether to plot the spectrogram

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

Returns:

• - A 2d array with spectrogram

• - info (a FieldMetaInformation object) – (see the corresponding docstring)