PSD Computation Tool

Outline

Purpose of this tool

This is a generic tool for manipulating a particle Phase Space Density. It provides the capability to take a slice through the distribution normal to an arbitrary vector as well as computing the usual moments of particle distributions: density, bulk velocity, pressure tensor, heat flux and temperature. It permits the user to specify a spacecraft potential and an energy cut off for moments calculation. It can also find the PSD values along a vector and convert the PSD into velocity space.

It is largely based on "Paschmann, G, AN Fazakerley, and SJ Schwartz: Moments of plasma velocity distributions, Analysis Methods for Multi-spacecraft Data, ISSI Scientific Report SR-001, 1998." Sets of parameters allow tuning the computation depending on the properties of the plasma and of the spacecraft.

It has been tested successfully by comparing its results to those produced by the PEACE and CIS teams on some arbitrarily chosen events.
You may contact the QSAS team at: qsassupp@gmail.com.

Input parameters

Phase-space distribution

The input data set as a time series of arrays. The data must be convertible to Joules ("SI_CONVERSION" attribute), and the coordinates system must be spherical (either latitude or co-latitude for the polar angle). The tool itself will determine which of the dimensions are the angle and energy coordinates.

The "ENTITY" attribute, if present, is used to determine the mass and charge of the particle, but these may also be manually selected.

There is an intrinsic ambiguity in the definition of Phase Space Density due to the possibility that the radial coordinate is given in terms of the flow direction or look direction. Note that for Cluster CIS uses Flow direction, whilst PEACE uses Look direction. This tool sets the measurement direction parity automatically when either PEACE of CIS data are dropped into the PSD data slot, but this must be set manually for other data sets.

Coordinate Systems

The Input PSD is usually in a local Spacecraft frame. On Cluster, PEACE uses SR2 while CIS uses ISR2 (which is close to GSE). To provide the output in a scientifically useful frame it is necessary to provide the spacecraft spin axis latitude and longitude in either GSE or GSM. The default is to assume GSE unless the Coordinate_System or Frame attribute is provided and set to GSM.

Alternatively, it is possible to provide a rotation matrix from the Data coordinate system to the target coordinate system.

The user can choose the output to be in either GSE or GSM (irrespective of the frame of Spacecraft axis Latitude and Longitude) or an arbitrary frame determined by the input rotation matrix.

It is possible to generate and save only the rotation matrix from Data frame to chosen output frame for later use in this tool or elsewhere.

Spacecraft Potential

This is used to compensate for the effect of the particle acceleration in the vicinity of the spacecraft. The potential is converted to energy by multiplying it with the particle's charge. This value is subtracted from the energies in the distribution. Any resulting negative energies are discarded.It may be supplied as a numerical value in volts, or as a data object with a valid SI_conversion attribute. The default is to assume volts.

The potential must be a non-negative value.

Energy threshold

Energies under this threshold are discarded (applied before potential correction). This can be used to remove the effect of photoelectrons. No correction is done to compensate for the removal of this data. It may be provided as a numerical value in eV or as a data object with valid SI_conversion. The default is to assume eV.

Output options

Moments

The moments of the PSD in the selected coordinate system after taking account of the Spacecraft potential and selected lower energy cut off. It is possible to select all provided moments or just a selected subset using the tick boxes. The default is to generate only the density.

Slice PSD

This returns a two dimensional cartesian or polar slice through the PSD, normal to a specified direction.  It is possible to specify the number of bins required in (each dimension of) the array. The default result is in velocity space with axes binned in velocity and the slice in units of per velocity cubed, however, an option to return the slice in energy is provided. The x and y axes in the slice can be controlled by the choice of selection of the normal, see below.

Options are controlled by the following inputs:

Slice Centre

The slice is taken through the centre of the PSD distribution by default. It is, however, possible to specify a mean bulk velocity to subtract from the distribution before the slice is taken so that the resulting slice is centred in the bulk flow.

Slice Normal

The slice can be taken normal to any axis of the distribution in the target frame, X, Y or Z axis. It may also be taken normal to any specified vector in the target frame, but in this instance the X and Y directions are not user controlled, nor immediately obvious as the slice plane is simply rotated by the angle from the z-axis to the specified normal.

More control is provided by the last two options which take two vectors, V1 and V2, in order to define the orientation and axes of the slice. The normal to the slice can be either along V1, with V2 lying in the slice plane such that V2.X >0, or the normal can be perpendicular to the plane containing V1 and V2, i.e., in the V1 x V2 plane. In the latter case, V1 defines the X direction of the plane. In typical usage, V1 is the magnetic field direction and V2 the bulk flow velocity vector. Thus the first choice for the normal results in a slice perpendicular to B with the slice X-direction corresponding to the projection of the velocity onto that plane. The second choice corresponds to a slice in the V-B plane, with B along the slice X-direction.

In all cases the vectors supplied must be in the target frame of the distribution.

Since the input vectors may be of different time resolution to one another and to the input PSD, they will automatically be joined to the PSD timetags. The user may control the join options (linear interpolation or boxcar averaging) by pre-joining them first to the PSD.

Return as

The slice may be returned in velocity or energy space. The default is Velocity space. In either case the centre bulk velocity offset must still be specified as a velocity.

Slice Options

The number of bins may be specified, as well as whether they are laid out in polar or cartesian coordinates, and linearly vs logarithmically spaced.
Note that logarithmic spacing applies to the slice after applying the centre offset, while the underlying data distribution is likely to have
a logarithmic (or pseudo-logarithmic) spacing about the distribution centre.

Interpolation can be independently controlled for the radial and angular coordinates as well as the data values (counts, as these are often plotted with a logarithmic colour table). The default is to apply no interpolation for both radial and angular coordinates, in which case the original bin structure will appear in the slice. Note bin edges will look distorted with a slice at an arbitrary location and centre. Radial interpolation may be applied linearly or logarithmically, and the data values (counts) may also be interpolated oin the log.

3D -> 2D Reduced Distribution

Perform an integration along an input direction to reduce a 3D distribution to a 2D one. The integration is Cartesian in character and is accomplished by summing Cartesian slices taken at regularly-space intervals along the normal to the reduction plane, weighted by the velocity spacing to result in a true integration. The output is this integrated 2D distribution on a uniform rectangular velocity grid. Options include a specification of the normal and orientation of the output grid (as in the description of Slices given above). There are also options for the interpolation algorithms to be employed in velocity, angle, and values of f(v). Linear interpolation is probably safest, but none (=nearest neighbor) or logarithmic might be better in some circumstances. For best results use a grid that is fine enough to capture the features of interest in the output linear grid, and use the pull-down in the top Phase Space Distribution slot to restrict the energy/velocity range to avoid the grid spacing being set too large by the largest energies in the original data.

Pitch Angle Distribution

This returns a gyro-phase averaged pitch angle distribution as a 2D array in polar coordinates, taking as inputs the velocity-space origin from which to calculate pitch angles and the field direction. User input includes the number of energy bins, pitch angle bins, and also the number of gyrophase cuts, equally spaced in phi, used to perform the average.

Rotation Matrix

The rotation matrix from PSD frame to target frame is returned, but no other calculation performed.

Convert to Velocity

The PSD is returned to the working list, but converted into velocity space. The particle charge species is taken into account in calculating the equivalend velocity, and the result is in Look or Flow direction the same as the input PSD.

Values along a vector

The PSD values (counts) are returned along the specified vector. The PSD centre and number of bins may be controlled as per the slice option.

Algorithms

Formulas used

Let E be an energy value. If E is lower than the photoelectron threshold, nothing is done. Else, E'=E+P.C, where P is the non-negative potential of the spacecraft and C the signed charge of the particle.

If E' is non-negative, it is converted into velocity v, knowing that 2E'=mv.v (m for the particle mass) and knowing the measuring probe coordinates (and the GSE transformation matrix).

If f is the distribution function, the computed moments are:

The integration itself can be done using any of the following two methods.

Integration method 1: sum over bins

This method is the faster of the two, it is also the most naive one. It simply consists in the sum of the elementary integrations over the bin volumes, simply approximated by multiplying the data values over the bin volumes.

In the following illustrations, the principles are shown on a partial coverage of a 2D plane. The data values are shown as red shades, and the bin boundaries are dashed lines.

A part of the 2D plane is segmented into bins, each one carrying a value.


As illustrated on two bins, the integrated value is the value multiplied by the bin volume. These values are summed to give the total integrated result.

Despite its speed, this method is flawed when the data is sparse, as gaps are not filled.