Analysis Package Documentation

Trajectory Module

class IDSimPy.analysis.trajectory.OptionalAttribute(value)

Optional trajectory attributes identifiers: Distinct and extensible identifiers for optional trajectory data attributes.

PARTICLE_CHARGES = 2

Particle charges

PARTICLE_MASSES = 1

Particle masses

class IDSimPy.analysis.trajectory.ParticleAttributes(attribute_names_float=None, attributes_float=None, attribute_names_int=None, attributes_int=None)

Container class for heterogeneous particle attributes. This container class can store a set of named additional attributes for every particle of a trajectory, for every time step. The attributes can be of type float or integer. The two sets of attributes are stored in different arrays internally, and are therefore passed seperately to the constructor.

Similarly to internal representation of positions in Trajectory class, the shape of the internal arrays depends if the trajectory this ParticleAttribute object is belonging to is static or not:

• If the trajectory is static: The internal arrays are numpy.ndarray with the shape [n ions, particle attribute, n time steps]. With 5 particles, 4 additional numerical attributes (e.g. x,y,z and velocity) and 15 time steps the shape would be [5, 4, 15].

• If the trajectory is not static: The internal arrays are lists of numpy.ndarray with the shape [particle attribute, n ions]

Constructs a new particle attribute container.

The names and actual attribute data for floating point (float) and integer attributes are passed seperately.

Parameters:

• attribute_names_float – List of attribute names of the float attributes, can be None if no floating point attributes are stored

• attributes_float (np.ndarray or list of np.ndarray) – Floating point attribute data. Either three dimensional np.ndarray for static data or list of two dimensioal np.ndarray for non static data

• attribute_names_int – List of attribute names of the integer attributes, can be None if no integer point attributes are stored

• attributes_int – Integer point attribute data. Either three dimensional np.ndarray for static data or list of two dimensioal np.ndarray for non static data

property attribute_names

Names of all stored parameter attributes

get(attrib_name, timestep_index=None)

Gets and returns individual particle attributes.

Attributes are specified by their name. If the time step index is not specified, the attribute is returned for all time steps. If the particle attributes are static this is an two dimensional array with the dimensions [n particles, n time steps]. For non static particle attributes this is a list of vectors (arrays with one column) with the length of [n particles].

If the time step index is specified, a vector (arrays with one column) with length of [n particles] is returned.

Parameters:

• attrib_name (str) – Name of the particle attribute to return.

• timestep_index (int) – Index of the time step to return (can be Null for all time steps)

get_attribs_for_particle(particle_index, timestep_index)

Returns a list of the particle attributes for a single particle at a specified time step.

Parameters:

• particle_index (int) – The index of the particle to get the attributes for

• timestep_index (int) – The index of the time step to get the attributes for

property number_of_attributes

Number of stored particle attributes

property number_of_timesteps

Number of time steps particle attribute data is stored for

select(selected_particle_indices)

Select individual particles based on their indices and return new ParticleAttribute container for the selected particles.

The selector data in selected_particle_indices can be a simple vector of indices to select, if the particle attributes are static. If not, a list of selected indices is expected, one entry per time step. Note that this variable selection mode is also possible for static particle attributes.

Parameters:

selected_particle_indices (vector of int or list of vector of int) – Indices to select

class IDSimPy.analysis.trajectory.StartSplatTrackingData(start_times, start_positions, start_velocities, splat_times, splat_positions, splat_velocities, splat_states)

Simple container class for start / splat data of simulated particles

Constructs a new StartSplatTrackingData container

Parameters:

• start_times (np.ndarray with shape (n_ions, 3)) – A vector of start times for the particles (1 dimensional numpy array)

• start_positions – A vector of start positions of the particles (numpy array with three columns)

• start_velocities (np.ndarray with shape (n_ions, 3)) – A vector of start velocities of the particles (numpy array with three columns)

• splat_times (np.ndarray with shape (n_ions, 1)) – A vector of splat times for the particles (1 dimensional numpy array)

• splat_positions (np.ndarray with shape (n_ions, 3)) – A vector of splat positions of the particles (numpy array with three columns)

• splat_velocities (np.ndarray with shape (n_ions, 3)) – A vector of splat velocities of the particles (numpy array with three columns)

• splat_states (np.ndarray with shape (n_ions, 1)) – A vector of splat state for the particles (1 dimensional integer numpy array)

splat_positions: ndarray

splat_states: ndarray

splat_times: ndarray

splat_velocities: ndarray

start_positions: ndarray

start_times: ndarray

start_velocities: ndarray

class IDSimPy.analysis.trajectory.Trajectory(positions=None, times=None, particle_attributes=None, start_splat_data=None, optional_attributes=None, file_version_id=0)

An IDSimF particle simulation trajectory. The simulation trajectory combines the result of an IDSimF particle simulation in one object. The trajectory consists of the positions of simulated particles at the time steps of the simulation, the times of the time steps and optional attributes of the simulated particles.

The trajectory can be “static” which means that the number of particles is not changing between the time steps.

Variables:

• positions –

  Particle positions. The particles are stored in a different scheme, depending if the trajectory is static:

  • If the trajectory is static: positions is a numpy.ndarray with the shape [n ions, spatial dimensions, n time steps]. With 5 particles and 15 time steps the shape would be [5, 3, 15].

  • If the trajectory is not static: positions is a list of numpy.ndarray with the shape [spatial dimensions, n ions]

• times – Vector of simulated times for the individual time frames.

• n_timesteps – Number of time steps in the trajectory

• particle_attributes – Optional simulation result attributes for the simulated particles. Basically, particle attributes are a vector of numeric additional particle attributes, attached to every particle in every time step. The particle attributes are provided in a dedicated container class ParticleAttributes

• start_splat_data – Optional information about particle start and particle termination (splat) times and locations, which is also stored in a dedicated container class StartSplatTrackingData

• optional_attributes – dictionary of optional / free form additional attributes for the trajectory

• is_static_trajectory – Flag if the trajectory is static.

Constructor: (for details about the shape of the parameters see the class docsting)

Parameters:

• positions (numpy.ndarray or list[numpy.ndarray]) – Particle positions

• times (numpy.ndarray with shape [n timesteps, 1]) – Times of the simulation time steps

• particle_attributes (ParticleAttributes) – Additional attributes for every particle for every time step, provided by a ParticleAttributes container object

• start_splat_data (StartSplatTrackingData) – Particle start and termination (“splat”) tracking data (start / splat times and positions)

• optional_attributes (dict) – Optional attributes dictionary

• file_version_id (int) – File version id

file_version_id: int

get_n_particles(timestep_index=None)

Returns the static number of particles in a static trajectory

Returns:

Number of particles in the static trajectory

Return type:

int

get_particle(particle_index, timestep_index)

Get particle values (positions and additional attributes) for a particle at a specified time step

Parameters:

• particle_index (int) – The index of the particle

• timestep_index (int) – The index of the time step

Returns:

Tuple with the position and the attribute vector for the particle at the selected time step

Return type:

tuple of two numpy.ndarray

get_positions(timestep_index)

Get particle positions for a time step

Parameters:

timestep_index (int) – The index of the time step to get the positions for

Returns:

Array of particle positions for a time step. Dimensions are [n particles, spatial dimensions]

Return type:

numpy.ndarray

property n_particles

Returns the static number of particles in a static trajectory

Returns:

Number of particles in the static trajectory

Return type:

int

particle_attributes: ParticleAttributes

start_splat_data: StartSplatTrackingData

times: ndarray

IDSimPy.analysis.trajectory.center_of_charge(trajectory)

Calculates the center of charge of an ensemble of particles in a Trajectory.

Note: If there is no explicit information about the particle charges in the input trajectory object (the optional trajectory attribute OptionalAttribute.PARTICLE_MASSES is not present) all particles are assumed to be singly positively charged.

Parameters:

trajectory (Trajectory) – Trajectory to calculate the center of charge for

Returns:

Vector of the spatial position of the center of mass: Array with time steps as first and spatial dimension (x,y,z) as second dimension

Return type:

numpy.ndarray

IDSimPy.analysis.trajectory.export_trajectory_to_vtk(trajectory: Trajectory, vtk_file_base_name)

Translates and exports an ion trajectory to a set of legacy VTK ascii files

Parameters:

• trajectory – The trajectory to translate and export

• vtk_file_base_name (str) – The base name of the vtk files to generate

IDSimPy.analysis.trajectory.filter_attribute(trajectory, attribute_name, value)

Filters select ions according to a value of a specified particle attribute. The method takes a Trajectory the name of a particle attribute and a value which is selected for and constructs a new Trajectory from the filtered data.

Currently optional trajectory attributes and splat times are not retained.

This method returns always a variable, non static Trajectory.

Parameters:

• trajectory (Trajectory) – Trajectory object with the trajectory data to filter for

• attribute_name (str) – Name of a particle attribute to filter for

• value – Value to filter for: This value is used as selector

Returns:

A Trajectory object with filtered particle positions

Return type:

Trajectory

IDSimPy.analysis.trajectory.filter_for_active_particles(trajectory)

Select only active (non splatted) particles from a trajectory and constructs a new trajectory from it

Parameters:

trajectory – Input trajectory

IDSimPy.analysis.trajectory.is_active_particle(trajectory, true_val=True, false_val=False)

Constructs a selection map / boolean array which particles are active in the individual time frames

Parameters:

trajectory – Input trajectory

IDSimPy.analysis.trajectory.read_hdf5_trajectory_file(trajectory_file_name)

Reads a version 2 or 3 hdf5 trajectory file (which allows also exported simulation frames with variable number of particles.

Parameters:

trajectory_file_name (str) – Name of the file to read

Returns:

Trajectory object with trajectory data

Return type:

Trajectory

IDSimPy.analysis.trajectory.read_json_trajectory_file(trajectory_filename)

Reads a json trajectory file and returns a trajectory object

Parameters:

trajectory_filename (str) – File name of the file to read

Returns:

Trajectory object with trajectory data

Return type:

Trajectory

IDSimPy.analysis.trajectory.read_legacy_hdf5_trajectory_file(trajectory_file_name)

Reads a legacy hdf5 trajectory file (with static particles per exported simulation frame)

Parameters:

trajectory_file_name (str) – The name of the file to read

Returns:

Trajectory object with trajectory data

Return type:

Trajectory

IDSimPy.analysis.trajectory.read_trajectory_file_for_project(project_name, file_type)

IDSimPy.analysis.trajectory.select(trajectory, selector_data, value)

Selects simulated particles according to given value in an array of selector data and constructs a new Trajectory with the selected data.

This method is primarily intended to provide a flexible mechanism to select particles from a trajectory with a custom constructed parameter to be used for selection.

Parameters:

• trajectory – The trajectory object to be selected from

• selector_data (numpy.ndarray or list of numpy.ndarray) –

  Selector data which assigns one value of a parameter to be used for selection to every particle.

  • if a vector (one dimensional array) is provided it is assumed, that the particle related parameter which is filtered for is stable across all time steps. This is only possible for static Trajectory objects.

  • An individual filtering for every time step is done when a list of selector data vectors, one per time step, is provided. Every time step then has an vector of parameter values for the individual particles. This mode is possible for static an variable Trajectory objects.

• value – Value to select for: Particles with this value are selected from the trajectory object.

Returns:

Trajectory with selected data

Return type:

Trajectory

Chemistry Module

IDSimPy.analysis.chemistry.plot_concentration_file(filename, time_range=(0, 1))

Simple plot method: Reads and plots a IDSimF RS concentration log / result file

Parameters:

• filename (str) – name of the file to plot

• time_range (tuple of two float) – Begin and end of the time segment to plot. The begin and end times are given as relative fractions of the total length of the concentration file.

IDSimPy.analysis.chemistry.read_concentration_file(filename)

Reads a IDSimF RS concentration log / result file (tabular file with concentrations over time)

Parameters:

filename (str) – name of the file to read

Returns:

Pandas DataFrame with the imported data

Return type:

pandas.DataFrame

Visualization Module

IDSimPy.analysis.visualization.animate_scatter_plot(trajectory, xlim=None, ylim=None, zlim=None, n_frames=None, interval=1, color_parameter=None, crange=None, cmap=<matplotlib.colors.ListedColormap object>, projection='xy_xz', alpha=0.1, figsize=(13, 5))

Generates a scatter animation of the particles in a static ion trajectory.

Parameters:

• trajectory (Trajectory) – Static particle trajectory with data to animate

• xlim (tuple of two floats) – limits of the plot in x direction (if None, the maximum of the x position range is used)

• ylim (tuple of two floats) – limits of the plot in y direction (if None, the maximum of the y position range is used)

• zlim (tuple of two floats) – limits of the plot in z direction (if None, the maximum of the z position range is used)

• n_frames (int) – number of rendered frames, (if None the maximum number of frames is rendered)

• interval (int) – interval in terms of data frames in the input data between the animation frames

• color_parameter (str or iterable (ndarray, list, tuple)) – name of an additional parameter of the trajectory used for coloring or a vector of manual values for coloring

• crange (two element tuple of numeric) – manual color range, given as tuple. Colormap spans from c_range[0] to c_range[1]

• cmap (matplotlib.colors.Colormap) – a matplotlib colormap for colorization of the scatter plot

• projection (str) – Projection for the two plot panels, ‘xy_xz’ means xy on the left, xz on the right panel, ‘xy_yz’ means xy on the left, yz on the right panel

• alpha (float) – an alpha value for the plots

• figsize (tuple of two numbers) – size of the figure of the plot

Returns:

an animation object with the animation

IDSimPy.analysis.visualization.animate_variable_scatter_plot(trajectory, xlim=None, ylim=None, zlim=None, n_frames=None, interval=1, color_parameter=None, crange=None, cmap=<matplotlib.colors.ListedColormap object>, projection='xy_xz', alpha=0.1, figsize=(13, 5))

TODO:/ FIXME: Usage of color parameter is not yet implemented (only color parameter as aux parameter here)

Generates a scatter animation of the particles in an ion trajectory with varying particle number in the simulation frames

Parameters:

• trajectory (Trajectory) – a particle trajectory to be animated

• xlim (tuple of two floats) – limits of the plot in x direction (if None, the maximum of the x position range is used)

• ylim (tuple of two floats) – limits of the plot in y direction (if None, the maximum of the y position range is used)

• zlim (tuple of two floats) – limits of the plot in z direction (if None, the maximum of the z position range is used)

• n_frames (int) – number of rendered frames, (if None the maximum number of frames is rendered)

• interval (int) – interval in terms of data frames in the input data between the animation frames

• color_parameter (str or iterable (ndarray, list, tuple)) – name of an additional parameter of the trajectory used for coloring or a vector of manual values for coloring

• crange (two element tuple of numeric) – manual color range, given as tuple. Colormap spans from c_range[0] to c_range[1]

• cmap (matplotlib.colors.Colormap) – a matplotlib colormap for colorization of the scatter plot

• projection (str) – Projection for the two plot panels, ‘xy_xz’ means xy on the left, xz on the right panel, ‘xy_yz’ means xy on the left, yz on the right panel

• alpha (float) – an alpha value for the plots

• figsize (tuple of two numbers) – size of the figure of the plot

Returns:

an animation object with the animation

IDSimPy.analysis.visualization.animate_xz_density(trajectory, xedges=None, zedges=None, figsize=(7, 7), interval=1, n_frames=10, output_mode='animation', axis_equal=True)

Animates an density plot of a static simulation trajectory in a z-x projection. Still frames can also be rendered.

Parameters:

• trajectory (Trajectory) – Trajectory object with the particle trajectory data to be animated

• xedges (iterable or list / array or int) – the edges of the bins of the density plot (2d histogram bins) in x direction, if None the maximum extend is used with 50 bins, if a number n, the maximum extend is used with n bins

• zedges (iterable or list / array or int) – the edges of the bins of the density plot (2d histogram bins) in z direction, if None the maximum extend is used with 50 bins, if a number n, the maximum extend is used with n bins

• figsize (tuple of two floats) – the figure size

• interval (int) – interval in terms of data frames in the input data between the animation frames

• n_frames (int) – number of frames to render or the frame index to render if single frame mode

• output_mode (str) – returns animation object when ‘animation’, ‘singleFrame’ returns a single frame figure

• axis_equal (bool) – if true, the axis are rendered with equal scaling

Returns:

animation or figure

IDSimPy.analysis.visualization.animate_xz_density_comparison_plot(trajectories, selected, n_frames, interval, select_mode='substance', output_mode='video', mode='lin', s_lim=3, n_bins=100, basesize=17, alpha=1, colormap=<matplotlib.colors.LinearSegmentedColormap object>, annotate_string='')

Animate the densities of two mostly symmetric ion clouds (probably from a QIT simulation) in a z-x projection. The ion ensembles have to have an invariant number of particles across all time steps (static simulation trajectories).

Parameters:

• trajectories (tuple of Trajectory) – Tuple of two Trajectory objects with the data to animate

• selected (list of two selector values) – two element list with values to select particles which should be rendered

• n_frames (int) – number of frames to export

• interval (int) – interval in terms of data frames in the input data between the animation frames

• select_mode – defines the mode for selection of particles: None for not selecting at all, “mass” for selecting by mass, “substance” for chemical substance / chemical id

• output_mode – render either a video (“video”) or single frames as image files (“singleFrame”)

• mode – scale density linearly (“lin”) or logarithmically (“log”)

• s_lim – spatial limits of the rendered spatial domain (given as distance from the origin of the coordinate system or explicit limits: [xlo, xhi, zlo, zhi]

• n_bins (int or list of two ints) – number of density bins in the spatial directions or list of bin numbers ([x z])

• basesize (float) – the base (vertical) size of the plot

• alpha – blending factor for graphical blending the densities of the two species

• colormap – a colormap for the density rendering (a pure species will end up on one side of the colormap)

• annotate_string – an optional string which is rendered into the animation as annotation

Returns:

animation object or figure (depends on the file mode)

IDSimPy.analysis.visualization.plot_density_xz(trajectory, time_index, xedges=None, zedges=None, figsize=(7, 7), axis_equal=True)

Renders an density plot in a z-x projection

Parameters:

• trajectory (Trajectory) – Simulation trajectory with the data to plot

• time_index (int) – index of the time step to render

• xedges (iterable or list / array or int) – the edges of the bins of the density plot (2d histogram bins) in x direction, if None the maximum extend is used with 50 bins, if a number n, the maximum extend is used with n bins

• zedges (iterable or list / array or int) – the edges of the bins of the density plot (2d histogram bins) in z direction, if None the maximum extend is used with 50 bins, if a number n, the maximum extend is used with n bins

• figsize (tuple of two floats) – the figure size

• axis_equal – if true, the axis are rendered with equal scaling

IDSimPy.analysis.visualization.plot_particle_traces(pl_filename, particle_definitions, plot_mark='*-', time_range=(0, 1))

Plots the paths of a selection of particles in a x,z and y,z projection and saves the plot as pdf. To keep the function flexible, it takes a list of (trajectory, indices, label) tuples which specify the plotted particles and legend labels.

Indices can be a numeric index or a tuple of indices to draw multiple particle traces from a trajectory object.

Example:

particle_definitions = (
                (tra1, (1,2), 'trajectory 1'),
                (tra2, 3, 'trajectory 2')
        )

will plot from tra1 particle 1 and 2 with the label trajectory 1 and from tra2 particle 3 with the label trajectory 2.

Note: The trajectories are assumed to be static.

Parameters:

• pl_filename (str) – the basename of the plot image files to create

• particle_definitions (list of tuples of (Trajectory, int, str)) – Trajectory / particle definition input data

• plot_mark (str) – matplotlib plot format string which is used for the path-plots

• time_range (tuple of two floats between 0 and 1) – range of times to plot (given as normalized fraction between 0 and 1)

IDSimPy.analysis.visualization.render_scatter_animation(project_name, result_name, xlim=None, ylim=None, zlim=None, n_frames=None, interval=1, color_parameter=None, crange=None, cmap=<matplotlib.colors.ListedColormap object>, projection='xy_xz', alpha=0.1, fps=20, figsize=(13, 5), file_type='hdf5', only_active_particles=False)

Reads an ion trajectory file, generates a scatter animation of the particles in an ion trajectory and writes a video file with the animation

Parameters:

• project_name (str) – simulation project to read and animate (given as basename)

• result_name (str) – name of the result video file

• xlim (tuple of two floats) – limits of the plot in x direction (if None, the maximum of the x position range is used)

• ylim (tuple of two floats) – limits of the plot in y direction (if None, the maximum of the y position range is used)

• zlim (tuple of two floats) – limits of the plot in z direction (if None, the maximum of the z position range is used)

• n_frames (int) – number of rendered frames, (if None the maximum number of frames is rendered)

• interval (int) – interval in terms of data frames in the input data between the animation frames

• color_parameter (str or iterable (ndarray, list, tuple)) – name of an additional parameter of the trajectory used for coloring or a vector of manual values for coloring

• crange (two element tuple of numeric) – manual color range, given as tuple. Colormap spans from c_range[0] to c_range[1]

• cmap (matplotlib.colors.Colormap) – a matplotlib colormap for colorization of the scatter plot

• projection (str) – Projection for the two plot panels, ‘xy_xz’ means xy on the left, xz on the right panel, ‘xy_yz’ means xy on the left, yz on the right panel

• alpha (float) – an alpha value for the plots

• fps (int) – frames per second in the rendered video

• figsize (tuple of two numbers) – size of the figure of the plot

• file_type (str) – type of the trajectory file, ‘json’ for uncompressed json, ‘compressed’ for compressed json ‘hdf5’ for compressed hdf5

• only_active_particles (bool) – Render only currently active particles

IDSimPy.analysis.visualization.render_xz_density_animation(project_name, result_name, xedges=None, zedges=None, figsize=(7, 7), interval=1, n_frames=None, axis_equal=True, file_type='hdf5')

Renders an animation of particle density

Parameters:

• project_name (str) – simulation project to import and render (given as project basename)

• result_name (str) – basename for the rendering result

• xedges (iterable or list / array or int) – the edges of the bins of the density plot (2d histogram bins) in x direction, if None the maximum extend is used with 50 bins, if a number n, the maximum extend is used with n bins

• zedges (iterable or list / array or int) – the edges of the bins of the density plot (2d histogram bins) in z direction, if None the maximum extend is used with 50 bins, if a number n, the maximum extend is used with n bins

• interval (int) – interval in terms of data frames in the input data between the animation frames

• figsize (tuple of two floats) – the figure size

• interval – interval in terms of data frames in the input data between the animation frames

• n_frames (int) – number of frames to render or the frame index to render if single frame mode

• axis_equal (bool) – if true, the axis are rendered with equal scaling

• file_type (str) – type of the trajectory file, ‘json’ for uncompressed json, ‘compressed’ for compressed json ‘hdf5’ for compressed hdf5

IDSimPy.analysis.visualization.render_xz_density_comparison_animation(project_names, selected, result_name, select_mode='substance', n_frames=400, interval=1, s_lim=7, n_bins=50, base_size=12, annotation='', mode='lin', file_type='hdf5')

Reads two trajectories, renders XZ density projection of two ion clouds in the trajectories and writes a video file with the result.

Parameters:

• project_names (tuple of two strings) – simulation projects to compare (given as project basenames)

• selected (tuple of two floats) – list of masses in the two simulation projects to compare

• result_name – basename for the rendering result

• select_mode – defines the mode for selection of particles: “mass” for selecting by mass, “substance” for chemical substance / chemical id

• n_frames – number of frames to render

• interval (int) – interval in terms of data frames in the input data between the animation frames

• s_lim (float or list of two floats) – spatial limits of the rendered spatial domain (given as distance from the origin of the coordinate system or explicit limits: [xlo, xhi, zlo, zhi]

• n_bins (int or list of two ints) – number of density bins in the spatial directions or list of bin numbers ([x z])

• base_size (float) – the base size of the plot

• annotation (str) – annotation string

• mode – scale density linearly (“lin”) or logarithmically (“log”)

• file_type – type of the trajectory file, ‘hdf5’ for hdf5, ‘legacy_hdf5’ for old legacy hdf5 format, ‘json’ for uncompressed json, ‘compressed’ for compressed json