PEACEmoments CAA

Latest version: 0.7.7 (released on 2008-12-13)

Click here to see what has been changed

PEACEmoments CAA is easy-to-use software for calculating electron moments from PEACE CAA data. Some of the main features are:

input files are CDF and CEF files from the CAA
calculates density, velocity, energy flux, heat flux, pressure, temperature as well as currents
components of vectors and tensors parallel and perpendicular to the magnetic field can be calculated
moments are available in a number of different coordinate systems, including GSE and SR2
output files are in CEF2 format, which can be plotted easily using plotcf, gPlot, or QSAS
spacecraft potential correction is applied in moments calculations
spectrograms can be generated in order to help determine spacecraft potential offsets
moments plots are generated automatically, and can be adjusted to suit the individual user
the content of moments output files can be varied by the user
the moments output can be filtered; for example, spins containing WHISPER interference removed
data can be automatically promoted from the CAA if required

If you have SDDAS installed and want to calculate PEACE moments directly from IDFS data, please use the original PEACEmoments software, available from here (PEACE Co-I password required).

It is strongly recommended to use CDF files rather than CEF files as CDF files are binary, and hence can be read much more quickly and have smaller file sizes. Calculation of moments from CDF files is significantly faster than from CEF files.

PEACEmoments CAA is still in an early stage of development. Feature requests and bug reports are most welcome. Please email adl@mssl.ucl.ac.uk.

Downloads

The current beta version of PEACEmoments CAA can be downloaded here:

Linux x86 (32-bit)	Mandrake 9.2
Linux x86 (32-bit)	Fedora Core 7, OpenSUSE 11
Linux x86_64 (64-bit)	Fedora Core 9
Mac OS X (Intel)	Mac OS 10.5.5
Solaris (SPARC)	Solaris 10
Windows	Windows XP
source code	Qt >= 4.4.0 and CDF libraries required

Installation instructions are available here. Note that the Linux and Solaris binaries as well as the source code are updated every night (UK time), however the Mac OS X and Windows binaries are only updated whenever there are major changes or improvements made.

The main window

To launch PEACEmoments CAA on a Linux or Unix system, just type:

peacemoments-caa

The main window should then appear on the screen. (Here we have assumed the the directory containing the PEACEmoments CAA executable has been added to the user's PATH. If not, you will need to specify the full path to the executable).

On Mac OS X and Windows, double-click on the PEACEmoments CAA icon to launch the application.

The top two-thirds of the main window consists of two tabs: Input files and Download data.

The Input files tab allows users to specify up to 5 input CDF or CEF files: PEACE sensor 1, PEACE sensor 2, Spacecraft potential, AUX SP, and Magnetic field. If data from just one PEACE sensor is required, this should be specified as PEACE sensor 1. Note that it doesn't matter which is LEEA and which is HEEA. An AUX SP file only needs to be specified if moments are required in the GSE, SR2 or ISR2 coordinate systems. An FGM magnetic field file only needs to be specified if parallel and/or perpendicular components of moments are required. The filenames can either be typed in directly by the user, or the file system can be browsed.
The Download data tab allows users to select up to 5 files to download from the CAA, along with the required date and time range. A valid CAA username and password is required.

The bottom third of the main window is always the same, and more details about these functions are provided later. A brief summary of the buttons along the bottom of the main window:

Calculate: calculate moments. Moments calculations are carried out in a separate thread to the GUI, which means that the GUI will remain fully responsive during moments calculations. The Calculate button itself, however, is disabled when moments calculations are being carried out.
Integration: open the Integration settings window.
Output: open the Output settings window.
Plots: open the Plot setings window.
Load: load previously-saved settings from a .xml file.
Save: save current settings to a .xml file.
Quit: immediately quit PEACEmoments CAA. You will not be given the chance to change your mind.

At the very bottom of the main window is the status bar. Messages appear here describing what PEACEmoments CAA is currently doing. For example:

Calculating moments...
Generating spectrogram...

At the far right of the status bar is the progress bar. During a moments calculation, this indicates the progress of the calculation in the form of a horizontal bar and as a percentage.

Keyboard shortcuts

(Currently not available on Mac OS X).

An underlined character in the name of a button indicates that there is a keyboard shortcut. Note that the available shortcuts depend on what window is in the foreground. For the main window:

Alt+C begins a moments calculation
Alt+I opens the Integration settings window
Alt+O opens the Output settings window
Alt+P opens the Plot settings window
Alt+L will allow the user to select a .xml file to load
Alt+S will allow the user to specify a .xml file to save the current GUI setings to
Alt+Q will quit

For the Output settings window:

Alt+S will save all the currently-selected settings as the defaults
Alt+C will close the window

For the Plot settings window:

Alt+P will plot a spectrogram
Alt+R will plot moments
Alt+S will save all the currently-selected settings as the defaults
Alt+C will close the window

For the Integration settings window:

Alt+C will close the window

Coordinate systems

There are 5 possible coordinate systems available:

Sensor - the PEACE instrument coordinate system. This is aligned with the PEACE LEEA sensor.
Spacecraft - the body-build or spacecraft coordinate system. Also called the attitude system in the Data Delivery Interface Document (DDID). The x-axis lies along the nominal spin axis.
GSE - the Geocentric Solar Ecliptic coordinate system.
SR2 - the despun spin reference (SR) coordinate system. The z-axis is aligned with the SR z-axis, and the x-axis is in the meridian containing the direction of the sun.
ISR2 - inverted SR2 coordinate system, which is obtained after rotation of the SR2 coordinate system through 180^o about its x-axis.
B-field aligned - a coordinate system where the z-axis is parallel to the magnetic field. Currently only available when PITCH_FULL or PITCH_FULL_LAR data is used.

Note that components of moments parallel and perpendicular to the magnetic field are only available in the GSE, SR2 and ISR2 coordinate systems, provided that an appropriate FGM file containing the magnetic field vector in GSE is specified.

The GSM (Geocentric Solar Magnetic) coordinate system will be available in a future release of PEACEmoments CAA.

Sensor combinations

The are 10 possible sensor combinations available. If only a data file for a single PEACE sensor is specified, then, as expected, the only option is to just use data from this sensor. If, however, data from both the LEEA and HEEA sensors is used, the user has freedom in how the data is combined from the two sensors.

The most common situation is when both sensors partially overlap, with HEEA covering the high energies and LEEA covering the low energies.

HEEA high energies, LEEA low energies

There are 3 different energy regions: top (T), overlap and bottom (B). In this example, T is from the HEEA sensor and B is from the LEEA sensor. In the overlap energy region data is available from both the LEEA and HEEA sensors. Available data from the overlap energy region:

L1 - LEEA data from the first half of the spin in the overlap energy region
L2 - LEEA data from the second half of the spin in the overlap energy region
H1 - HEEA data from the first half of the spin in the overlap energy region
H2 - HEEA data from the second half of the spin in the overlap energy region

Another common (but less common than HEEA and LEEA partially overlapping), is when one sensor completely overlaps the other sensor. In the example diagram below, HEEA completely overlaps LEEA.

complete LEEA overlap

Here, both the T and B data is from the HEEA sensor. In the overlap energy region, L1, L2, H1, and H2 data is available.

The type of overlap depends on the instrument setup used (sweep presets and sweep modes).

The 11 different sensor combinations available in PEACEmoments CAA are:

LEEA - data from the LEEA sensor only
HEEA - data from the HEEA sensor only
TL1L2B - the B and T data is from the appropriate sensors, with LEEA data used from both halves of the spin in the energy overlap region
TH1H2B - the B and T data is from the appropriate sensors, with HEEA data used from both halves of the spin in the energy overlap region
TL1L2 - T data is used from the appropriate sensor, with LEEA data used from both haves of the spin in the energy overlap region
TH1H2 - T data is used from the appropriate sensor, with HEEA data used from both halves of the spin in the energy overlap region
L1L2B - B data is used from the appropriate sensor, with LEEA data used from both halves of the spin in the energy overlap region
H1H2B - B data is used from the appropriate sensor, with HEEA data used from both halves of the spin in the energy overlap region
L1L2 - LEEA data from the first and second halves of the spin are used, from the energy overlap region only
H1H2 - HEEA data from the first and second halves of the spin are used, from the energy overlap region only
Overlap 2-sec - (can be used for PITCH_FULL or PITCH_FULL_LAR data only) LEEA and HEEA data in the energy overlap regin is combined together twice per spin

When LEEA and HEEA partially overlap, with HEEA covering the high energies, HEEA is equivalent to TH1H2 and LEEA is equivalent to L1L2B. However, for other combinations of sweep presets and modes, this is not necessarily true.

What sensor combination should I use?

When data is available from both LEEA and HEEA, either partially overlapping or one sensor completely overlapping the other, use:

TL1L2B - if there is a chance that HEEA might be saturated. This sensor combination is most suitable for high-density plasmas, for example, the magnetosheath.
TH1H2B - for lower density plasmas, for example, the plasma sheet, where HEEA is not likely to be saturated.

If both sensors cover the same energy region, use:

LEEA - if there is a chance that HEEA might be saturated, for example, the magnetosheath.
HEEA - for lower density plasmas.

What happens if the available data during a time period changes?

Sometimes a user may be interested in a time period that contains both two-sensor data and data from just one sensor. For example, both LEEA and HEEA data may be available for the first half of the time period, and LEEA data only is available for the second half of the time period. In this case, the user should select a two-sensor combination, for example TL1L2B. For the second half of the time period, when only LEEA data is available, then LEEA will be used as the sensor combination.

Consider another example. LEEA and HEEA data, partially overlapping, is available for the first half of a time period, and LEEA and HEEA data covering the same energy range is available for the second half of the time period. In this case, if the user selects TL1L2B as the sensor combination, LEEA data will be used for the second half of the time period, not HEEA. If, on the other hand, the user selects TH1H2B as the sensor combination, HEEA data will be used for the second half of the time period, not LEEA.

Spacecraft potential correction

The following method is used for spacecraft potential correction in PEACEmoments CAA. Firstly, all energy bins entirely below the spacecraft potential are ignored. If the spacecraft potential lies within an energy bin, this energy bin is also ignored. The acceleration of the electrons due to the spacecraft potential is removed by subtracting the spacecraft potential from the lower and upper energy limits of the remaining energy bins, i.e.

E_L is replaced with E_L - V_SCP
E_U is replaced with E_U - V_SCP

where E_L is the lower limit of an energy bin, and E_U is the upper limit of an energy bin. Here V_SCP is a positive spacecraft potential, i.e. it has the opposite sign to the EFW spacecraft potential data in the CAA.

It is possible for the user to apply a constant offset to the spacecraft potential. Generally around 1 eV is always added to the value obtained from EFW, and this is the default value in PEACEmoments CAA.

A second offset is also available - the Low energy cutoff offset. This allows users to increase low energy integration cutoff, and can be specified in units of bins or eV. If this offset is specified as 2 bins, for example, the first 2 energy bins above the spacecraft potential will be ignored, and not included in the energy integration. This can be used to remove photoelectrons (or other electrons) in the energy bin(s) just above the spacecraft potential.

Downloading data from the CAA

The Download data tab allows users to automatically download all required data from the CAA for calculating moments. This includes PEACE data, EFW spacecraft potential data, AUX SP data (requred for GSE and B-field aligned moments, as well as FGM B-field data.

After selecting the required time interval and data, click the Download button. A message will appear at the bottom of the window "Request sent to CAA, waiting for response...". Depending on how much data has been requested, this message will be present for quite some time (in the order of minutes). This is due to the speed of the CAA website. Eventually a message "Downloading data..." will appear, indicating that data is being downloaded from the CAA.

Once the data has been downloaded from the CAA, it is unzipped and placed in a unique directory, e.g. Data004. The Input files page is automatically updated to include the correct paths for each file.

Saving default settings

Some settings can be saved as the user's default settings. Whenever PEACEmoments CAA is launched, these settings will be restored. The method used to store these settings depends on the operating system. In the Output settings window, all Output file content and Output filtering settings can be saved. In the Plot settings window, all Moments plot settings can be saved.

Load / save

GUI settings can be saved as .xml files, and restored later. Note that the settings from .xml files will take preference to the user's saved default settings for the Output settings and Plot settings windows.

If you specify a .xml file when PEACEmoments CAA is launched, the GUI will be setup as specified in the .xml file. For example:

peacemoments-caa my-moments.xml

Output settings

The Output settings window allows users to specify the location, name and content of the output moments files.

Output directory

By default, output files are generated in the current directory. If you want to generate output files in a different location, specify the directory or create a new one.

Moments output file

By default, the output filename is moments.cef. If you want a different name, set it here. Note that PEACEmoments CAA will silently over-write an pre-existing files.

Output file content

This allows users to specify exactly what moments should be included in the moments output files.

Output filtering

This allows users to remove "bad" data, as determined by status variables in the PEACE data files. The options are:

Remove spins with poor quality data
Remove spins containing possible WHISPER interference
Remove spins containing possible EFW interference
Remove spins with possible poor statistics or saturation
Remove spins with datastream errors

Out of all of these, the most useful one would be to remove spins during which WHISPER was active.

As mentioned previously, the user's favourite choices for Output file content and Output filtering can be saved as the default settings, which will be restored whenever PEACEmoments CAA is launched.

Plot settings

The Plot settings window consists of two main parts: Spectrogram and Moments plot.

Spectrogram

Click Plot to generate a spectrogram using the currently specified PEACE data files. Spectrograms can be saved as png images by clicking on Save as.... The filename specified should end in ".png". The y-axis lower and upper limits can be specified, as well as the colour scale lower and upper limits. Spectrograms can be made in a choice of 3 different units: Differential energy flux, Differential number flux, or Phase space density. (Note that only PEACE input CDF/CEF files in phase space density are accepted by PEACEmoments CAA. Phase space density is converted to differential energy flux or differential number flux if the user requests a spectrogram with these units).

If an EFW spacecraft potential has been specified, by default the potential will be overlaid on the PEACE spectrogram, and all energy bins will be plotted. The Energy option allows you to change this behaviour. For example, only energy bins above the spacecraft potential can be plotted. This is useful for deciding what to use for the spacecraft potential Low energy cutoff offset. Another option is to generate a spacecraft potential corrected spectrogram. In this case no EFW potential is shown; instead, the spacecraft potential is subtracted from the lower and upper limits of all energy bins.

The Sensors option is only useful when data from both LEEA and HEEA is being used. It allows you to see just the contribution from either the LEEA or HEEA sensor on its own.

Spectrograms are generated in a separate thread to the GUI, which means that the GUI will remain fully responsive during generation of spectrograms. The Plot button itself, however, is disabled while a spectrogram is being generated. Note that spectrograms can be generated at the same time while a moments calculation is progress (the spectrogram generation and moments calculation take place in different threads).

Moments plot

By default, moments plots are automatically generated and shown on the screen after moments are calculated. This feature can be switched off by clicking the check box next to Moments plot. The user can select exactly what should be plotted in the moments plots. Click Replot to generate a new plot using the most recently-generated output file, or click Save as... to save the moments plot as a png file. The filename specified should end in ".png".

Moments plots are generated in a separate thread to the GUI, which means that the GUI will remain fully responsive during generation of moments plots.

The user's favourite set of moments to be included in moments plots can be saved as the default settings, as mentioned previously, and restored whenever PEACEmoments CAA is launched.

If more control over plotting is required, the companion software plotcf is recommened for quickly making plots. An alternative is QSAS.

Integration settings

Restricted energy integration

This allows the user to specify lower and upper energy integration limits. If you wish to specify a lower limit only, set the upper limit to an energy at least as high as the highest energy measured by PEACE. Using a very high energy such as 40000 eV is always a safe choice. If you wish to specify an upper limit only, set the lower limit to 0 eV.

By default, only complete energy bins within the user-defined energy integration limits will be included in the energy integration. When Use exact energy limits is checked, the lower and upper integration limits will be exactly as specified by the user. Simple interpolation will be used to include contributions from any energy bins containing the user's lower energy limit and upper energy limit.

When the energy integration is being carried out and it is deciding whether or not to include an energy bin, the energy bin lower and upper limits either before or after spacecraft potential correction can be considered. For high energies the difference will be negligible, but for low energies the difference might be important. Click Spacecraft potential corrected energies if the user specified lower and upper limits correspond to the actual energies of the electrons (for example, you decide on particular energy limits by looking at a spacecraft potential corrected spectrogram). If you decide on particular energy limits by looking at a spectrogram with no spacecraft potential correction, ensure that Spacecraft potential corrected energies is not checked.

Restricted polar integration

This allows the user to calculate moments using specific polar bins (or pitch angle bins for the case of PITCH_FULL or PITCH_FULL_LAR data). The number of polar bins depends on the data product being used. 3DR, 3DXP and 3DXPLAR have 6 bins, while 3DX, 3DXLAR, PITCH_FULL and PITCH_FULL_LAR have 12 bins.

Output files

The output files generated by PEACEmoments CAA are CEF2 files. These are ASCII files containing a header which describes the content of the files. CEF2 files can easily be converted to other formats, for example CDF, using Qtran.

Some details about the moments calculation are available in the following global metadata:

INPUT_FILE_PEACE1: the filename used for PEACE sensor 1
INPUT _FILE_PEACE2: the filename used for PEACE sensor 2
INPUT_FILE_POTENTIAL: the filename used for the spacecraft potential
INPUT_FILE_AUX_GSE: the filename used for the AUX SP data
INPUT_FILE_MAG_FIELD: the filename used for the FGM magnetic field
SC_POTENTIAL_CORRECTION: this is either ON or OFF.
SC_POTENTIAL_OFFSET: this specifies the spacecraft potential offset used.
SC_POTENTIAL_LOW_ENERGY_CUTOFF_OFFSET: this specifies the offset to the low energy integration cutoff, and the units used, which are either bins or eV.
RESTR_ENERGY_INT: this is either ON or OFF. ON means that the user has specified restricted energy integration limits.
RESTR_ENERGY_EN_SCP: this is either NO_POTENTIAL_CORRECTION or POTENTIAL_CORRECTED.
RESTR_ENERGY_TYPE: this is either NORMAL or INTERPOLATED.
RESTR_ENERGY_LOW: the low integration limit
RESTR_ENERGY_HIGH: the upper integration limit
RESTR_POLAR_INT: this is either ON or OFF. ON means that the user has specified restricted polar bin integration limits.
RESTR_POLAR_LOW: the lower polar bin limit
RESTR_POLAR_HIGH: the upper polar bin limit

Some mode information is always included in the output files as Support_Data variables:

Mode_Sensor: this is the sensor(s) from which the PEACE data was collected. 0 = HEEA, 1 = LEEA and 2 = both HEEA and LEEA.
Mode_SweepMode_HEEA: this is the HEEA sweep mode. 0 = off or fixed energy, 1 = LAR (Low Angular Resolution), 2 = HAR (High Angular Resolution) and 3 = MAR (Medium Angular Resolution).
Mode_SweepMode_LEEA: this is the LEEA sweep mode. 0 = off or fixed energy, 1 = LAR, 2 = HAR and 3 = MAR.
Mode_TopRegionSensor: specifies which sensor was used for the top energy region. 0 = HEEA, 1 = LEEA, 2 = average of HEEA and LEEA.
Mode_OverlapRegionSensor: specifies which sensor was used for the overlap energy region. = 0 = HEEA, 1 = LEEA, 2 = average of HEEA and LEEA.
Mode_BottomRegionSensor: specifies whichs ensor was used for the bottom energy region. 0 = HEEA, 1 = LEEA, 2 = average of HEEA and LEEA.

If data from just a single PEACE sensor is used, Mode_TopRegionSensor, Mode_OverlapRegionSensor and Mode_BottomRegionSensor are all set to fill values. Also, when just a single PEACE sensor is used, Mode_SweepMode for the sensor not being used is set to a fill value.

The sensor combination selected by the user is only mentioned in DATASET_TITLE. Note that the actual sensor combination used may differ from this, for example, if a time period sometimes contains data from two sensors and at other times just a single sensor. In this case the sensor combination may change depending on how many sensors are giving data, and the energy ranges covered by each sensor. The sensor combination used per spin can be determined from Mode_TopRegionSensor, Mode_OverlapRegionSensor and Mode_BottomRegionSensor.

Status information is also available in the output files, which comes directly from the PEACE input files.

Status_Quality_HEEA:
Status_CountStats_HEEA: 0 = okay, 1 = risk of low statistics, 2 = risk of saturation
Status_DatastreamErrors_HEEA: 0 = okay, 1 = bit-flip, 2 = DPU re-sync for 16-spins, 3 = DPU to sensor data transfer error
Status_Quality_LEEA:
Status_CountStats_LEEA: 0 = okay, 1 = risk of low statistics, 2 = risk of saturation
Status_DatastreamErrors_LEEA: 0 = okay, 1 = bit-flip, 2 = DPU re-sync for 16-spins, 3 = DPU to sensor data transfer error
Status_Eclipse: 0 indicates external sunpulse used, 1 indicates internal sunpulse used. When internal sunpulse mode is used, it is in general risky to compare PEACE moments to other instruments.
Status_InterferenceFromEFW: 0 indicates no interference, 1 indicates possible interference from EFW
Status_InterferenceFromWHI: 0 indicates no inteference, 1 indicates possible interference from WHI

If data from a single sensor is being used, the status variables for that particular sensor will contain fill values.

The moments included in the output files depends entirely on the user's settings in the Output file content section of the Output settings window.

Command line use

PEACEmoments CAA can easily be run from the command line, which is useful for batch processing, for example. The appropriate CDF/CEF files need to be specified, and there are simple ways to specify coordinate systems, sensor combinations, etc.

Calculating moments from .xml files

If you have previously saved GUI settings to a .xml file and wish to calculate moments from the command line, use the -run option. Example usage:

peacemoments-caa -run myfile.xml

No other arguments are required.

Basic command line generation of moments

The appropriate CDF/CEF data files need to be specified as arguments:

peacemoments-caa <PEACE file 1> <PEACE file 2> <EFW potential file> <AUX SP GSE file> <FGM B-field file>

The EFW, AUX, and FGM files are optional, however in most cases they will need to be specified. The files can be listed in any order.

Setting the output filename

The name of the moments CEF output file can be specified using the -o option. Example use:

peacemoments-caa <PEACE file 1> <PEACE file 2> <EFW potential file> <AUX SP GSE file> -o <moments file>

By default, moments.cef will be used if the user does not specify a filename.

Setting the coordinate system

The coordinate system can be set using the -c option. The possible options are SENSOR, SPACECRAFT, GSE, SR2 and ISR2.

Example use:

peacemoments-caa <PEACE file 1> <PEACE file 2> <EFW potential file> <AUX SP GSE file> -c GSE

Setting the sensor combination

The sensor combination can be set using the -s option. The possible options are LEEA, HEEA, TL1L2B, TH1H2B, TL1L2, TH1H2, L1L2B, H1H2B, L1L2, and H1H2.

Setting spacecraft potential offsets

An offset to the EFW spacecraft potential can be specified using the -off1 option. A positive value increases the magnitude of the potential, while a negative value makes the potential smaller. A low energy cutoff offset can be specified using the -off2 option. When setting the low energy cutoff offset, the units must also be specified. The units can either be bins or eV.

Example usage:

peacemoments-caa <PEACE file 1> <PEACE file 2> <EFW potential file> -off1 1.5 -off2 1 bins

Output file content

The default content of moments output files: n, v, v (para), v (perp), q, q (para), q (perp), h, h (para), h (perp), P, T, T (para), T (perp) and B. At the moment this cannot be changed. Please use the PEACEmoments CAA GUI, or generate .xml files, if you want to generate output files containing a different selection of moments.

Last update: 2009-02-22, A.D. Lahiff.