Standalone user applications such as plotaz and qjas are documented separately. The present pages document the programmer's interface to both high level routines and low level utilities, from which other applications may easily be written. In particular, full functionality is provided by the high-level routines:
Data Fetching
Routine | Module | Purpose |
add_secs_to_idfs_time | Qidfs_utils | Robust time arithmetic (to msec accuracy) |
advance_idf_file_spin_start | Qidfs_utils | Advance an idf file to the start of the next spin |
BIN_UNITS_STRING | Qidfs_utils | String of units for energy bin |
BIN_UNITS_SI_conv_STRING |
Qidfs_utils |
String for CSDS SI_conversion attribute for
energy bin |
check_bins | Qidfs_utils | Ensure energy bins have finite width |
clockstep | Qpeace_pad | Find start and direction for filled pitch angle bins given full 360 clock |
CombineSweeps | Qsweep_spin | Interpolation of one sweep onto bins of another, with weights |
compare_idfs_time | Qidfs_utils | Compare two times |
compute_clockbin | Qpeace_pad | Position 'round full polar clock of sensor |
copy_lineage | Qidfs_utils | Copy lineage strings and version to another lineage structure |
copy_spin |
Qsweep_spin | Make a full copy of a spin
structure |
create_sweep_full_copy | Qsweep_spin | Make a complete copy of a sweep of data |
cyclic360abs_diff | Qpeace_pad | Abs angular difference between two angles 'round a full circle |
cyclic360pos_diff | Qpeace_pad | Signed angular difference between two angles 'round a full circle |
diff_or_integral | Qidfs_utils | Decide if given psd units are an integral measure (e.g. counts) or density |
divide_by_area | Qsweep_spin | Divide psd array of a sweep by (typically area) weights |
e_bin_edges | Qidfs_utils | Get the energy bin limits in physical units |
epoch_secs_to_idfs_time | Qidfs_utils | Convert secs since 0AD to idfs time |
QEpochSecs | Qidfs_utils | (year, mon, day, hr, min, sec) -> secs since 00:00 on 0AD |
exchange_b_tip_tail | Qpeace_pad | flip flags for +B direction |
expected_first_polbin | Qpeace_pad | Use iel information to anticipate 1st filled sensor in 1st half of spin |
fill_pad | Qpeace_pad | Low level routine to fill PEACE sweep structure with PAD data |
fill_single_sen_sweep | Qsweep_spin | Lowest level routine to fill a sweep for a single PEACE sensor |
fill_spin3d | Qsweep_spin | High level routine to get and fill a spin's worth of data |
fill_sweep | Qsweep_spin | Low level routine to get and fill a single sweep of data. |
fill_sweep_bin_area | Qsweep_spin | Calculate polar areas of all sweep bins |
find_az_sweep | Qsweep_spin | Find the sweep within a spin which contains a given azimuthal direction |
find_subset_in_range | Qidfs_utils | Find bins in one set which overlap with given bin boundaries |
free_n_spins | Qsweep_spin | Free up memory malloced in n spin structures |
free_n_sweeps | Qsweep_spin | Free set of sweep structures, including bins and lineage |
free_spectro_arrays | Qpeace_plot | Free bin and z arrays in pgs |
free_spin_data | Qsweep_spin | Free up memory malloced by malloc_spin_sweep |
free_sweep_arrays | Qsweep_spin | Free up memory associated with sweep arrays. Use with caution! |
free_1D_cut_arrays | Qsweep_spin | Free up arrays malloced by sweep_1D_cut |
get_b_az | Qpeace_pad | Find azimuth of B from iel data. |
GetNPeaceSpins | Qsweep_spin | High-level to get sequence of PEACE Spins |
GetNPeaceSweeps | Qsweep_spin | High-level to get sequence of PEACE sweeps (incl PAD) |
GetNPeacePADs | Qpeace_pad | High-level to get sequence of pitch angle distributions from the PEACE PAD virtual instrument |
GetPeacePAD | Qpeace_pad | High-level to get a single pitch angle distribution from the PEACE PAD virtual instrument |
GetPeaceSpin | Qsweep_spin | Self-contained routine to return a full spin structure; all idfs calls internal to this |
idfs_time_to_epoch_secs |
Qidfs_utils |
Convert idfs time to CDF Epoch SECONDS since
midnight 0AD |
inbin | Qsweep_spin | Find bin which holds input value (rather trivial) |
init_idf_file | Qidfs_utils | Open and position an idfs data file |
init_pad | Qpeace_pad | Low-level initialisation routine for PAD virtual instrument |
init_spin3d | Qsweep_spin | Initialise a spin3d structure once a file is opened and roughly positions |
invert_array | Qidfs_utils | Invert the order of an array of floats |
malloc_spectro_arrays | Qpeace_plot | Malloc bin and z arrays in pgs |
malloc_spin_sweep | Qsweep_spin | Malloc internal arrays and sweep structures to hold spin data |
malloc_sweep_arrays | Qsweep_spin | Malloc sweep energy, angle arrays and lineage structure |
mod360 | Qidfs_utils | Return number modulo 360, i.e., in range 0->360 |
msec_nano_to_sec_nano | Qidfs_utils | Convert milliseconds with nanosec remainder to secs with nanosec remainder |
multiply_by_area | Qsweep_spin | Multiply psd array of a sweep by (typically area) weights |
near_nice_number | Qidfs_utils | Find 1,2, or 5 x power of ten nearest but > magnitude to input |
nsweeps2QiCDFContents | Qsweep_spin | Take many sweeps of data and fill a CDFContents Object for exporting data, bins, ... Underneath this are a suite of routines to set attributes and deal with the various variables (psd, bin boundaries, etc.) not documented here. |
nullify_sweep_arrays | Qsweep_spin | Initialize sweep array and lineage pointers to NULL |
PADLiouvilleMap | Qpeace_pad | Map pitch angle distribution using Liouville's Theorem |
PADvpara_boost |
Qpeace_pad |
Shift PAD (or sweep) by constant v_parallel. |
PeaceGetAzSlice | Qsweep_spin | Get a single azimuthal slice from and IDFS data holding |
PlotTwoSweeps | Qpeace_plot | Plot two azimuthal slices of IDFS data in a wheel plot |
polar_area | Qidfs_utils | Calculate the plane polar area of a given bin |
pos_idf_file_spin_start | Qidfs_utils | Position an idf file to the start of a spin |
print_bins | Qidfs_utils | Print out bin edges |
print_idf_data | Qidfs_utils | stdout print of idfs data time, sensor info, and some data for diagnostics |
print_idfs_lineage | Qidfs_utils | stdout idfs lineage project, mission, experiment, ... |
print_idfs_time | Qidfs_utils | sdtout idfs time in various formats |
print_peace_spin_info | Qsweep_spin | Print spin structure times, etc. to stdout |
print_sweep_structure | Qsweep_spin | Diagnostic dump of a sweep for all sensors |
print_weight | Qsweep_spin | Diagnostic dump of weight (or psd) array. |
print_1D_cut | Qsweep_spin | Diagnostic print of a 1-D cut structure |
PSD_UNITS_STRING | Qidfs_utils | String of units for phase space density |
PSD_UNITS_SI_conv_STRING |
Qidfs_utils |
String for CSDS SI_conversion file export |
QanDateToYearDoy | Qidfs_utils | (year, mon, day) -> (year, doy) |
QanYearDoyToDate | Qidfs_utils | (year, doy) -> (year, mon, day) |
QEpochSecs |
Qidfs_utils |
CDF Epoch in SECONDS since midnight 0AD |
Qjas_az_panel | Qpeace_plot | Plot bottom (azimuths) panel in Qjas_plot |
Qjas_fill_angle_t_array | Qpeace_plot | Fill spectrogram array; helper for Qjas_plot |
Qjas_lev_panel | Qpeace_plot | Plot angle/time spectrogram for a single level within Qjas_plot |
Qjas_plot | Qpeace_plot | Stack of angle/time spectrograms, one for each energy level |
Qjas_set_vpt_win_from_pgs | Qpeace_plot | Get PGPLOT ready for Qjas_plot |
qjas_time_init | Qpeace_plot | Time manipulation to support Qjas_plot |
rebin_sweep | Qsweep_spin | interpolate sweep data onto new energy/angle bins |
rebin_sweep_to_pa | Qsweep_spin | Rebin a set of sweeps onto a single pitch angle sweep structure |
Rebin_n_spins_to_pa | Qsweep_spin | Rebin set of spins to a set of pitch angle sweeps structures |
rebin_n_sweeps | Qsweep_spin | interpolate n sweeps onto new energy/angle bins |
Rebin_n_sweeps_to_pa | Qsweep_spin | Interpolate n sweeps grouped onto pitch angle sweep structures |
SC_NAME | Qidfs_utils | String of spacecraft name |
scale_then_rotate_angles | Qidfs_utils | Scale an angle, then rotate (really multiply a float, then add) |
sec_nano_to_msec_nano | Qidfs_utils | Convert seconds with nanosec remainder to millisecs with nanosec remainder |
set_b_para_half_spin | Qpeace_pad | Set the half spin which contains the +B field LOOK direction |
set_equal_bins | Qidfs_utils | Set equal size bins given min, max, number |
set_equal_bins_linlog |
Qidfs_utils |
Set bins equal in linear or log size |
set_equal_bins_half_ends |
Qidfs_utils |
Set bins equal in size but with half-sized end
bins |
set_pa_opts_defaults | Qsweep_spin | Set default options for pitch angle binning |
set_psd_tables | Qidfs_utils | Set the tables and operators to convert idfs data into physical units for counts, phase space density, differential energy flux, ... |
Set_Sweep_cut_options_default | Qpeace_plot | Defaults line,scaling, for Sweep cut plot routines |
Set_sweep_wheel_options_default | Qpeace_plot | Set default options (colours, scaling, ...) for a sweep wheel plot |
set_times_from_idf | Qidfs_utils | Get start, end, and sun sensor times from an idf data structure |
sinsq_map | Qpeace_pad | Compute new sin^2 pitch angle for Liouville mapping |
sort_pa_bins | Qpeace_pad | Sort filled/empty bins 'round full 360 clock |
sweep_arithmetic | Qsweep_spin | Add, subtract, multiply, or divide two sweeps (interpolates as necessary) |
sweep_double_levels |
Qpeace_pad |
Increase energy/velocity levels by factor 2 |
sweep_double_sensors | Qpeace_pad | Increase angular resolution by 2; crude interpolation and smoothing |
sweep_duration_calculator | Qsweep_spin | Take n sweep start times and calculate number of sweeps/spin |
Sweep_cuts_plot | Qpeace_plot | Take multiple cuts of multiple sweeps (No longer used; see Sweep_n_cuts_plot) |
Sweep_n_cuts_plot | Qpeace_plot | For n sweeps, take individually specified cuts. Better than Sweep_cuts_plot |
sweeps_autoscaler | Qsweep_spin | Find min and max data values in set of sweeps |
Sweep_wheel_plot | Qpeace_plot | Plot a sweep of data as (half of) a wheel plot |
sweep_1D_cut | Qsweep_spin | Select a 1D cut from a sweep structure |
t1_minus_t2 | Qidfs_utils | Take difference between two times |
test_sweeps_congruent | Qsweep_spin | See if two sweeps share same bin boundaries, units, ... |
to_hms_time | Qidfs_utils | Convert an IDFS time to hour, min, sec |
to_idfs_time | Qidfs_utils | Convert a date/time to IDFS_TIME format |
Prototype | Returns | Description |
SDDAS_SHORT GetPeaceSpin( IDFS_LINEAGE *lineage, IDFS_TIME *btime, BIN_UNITS bin_units, PSD_UNITS psd_units, T_OR_F do_pa, PEACE_SPIN3D *spinp ) |
PEACE3D_ERROR ALL_OKAY |
High level routine to fill a PEACE 3D spin structure. Can be called without any prior idfs routine calls, and likewsie tidies prior to return. Input lineage (including extension but excluding version), start time, bin units and psd units. Pass declared but empty spin structure. On return, spin structure has had internals malloced and filled. If do_pa = QPTRUE, the pitch angle for each measurement is returned in the pa array of the sweep structures. Free using free_spin_data. |
SDDAS_SHORT GetNPeaceSpins( IDFS_LINEAGE *lineage, IDFS_TIME *btime, IDFS_TIME *etime, BIN_UNITS bin_units, PSD_UNITS psd_units, T_OR_F do_pa, int *nspins, PEACE_SPIN3D ***spinppp); |
PEACE3D_ERROR ALL_OKAY |
High level routine to get a set of spins within a given time range. Mallocs the spin structures and internal arrays, returning an array of pointers in *spinppp. If do_pa = QPTRUE the sweeeps in each spin also will have pitch angle arrays filled (if the pa data is found; if not, an error is generated and no data is returned). Will put together data from more than one file by multiple calls to lower level routine GetN1PeaceSpins. |
PEACE_SWEEP *PeaceGetAzSlice( IDFS_LINEAGE *lineage, IDFS_TIME *btime, float az, BIN_UNITS bin_units, PSD_UNITS psd_units, PEACE_PITCH_ANGLE_OPTS *paopts) |
pointer to a complete sweep structure | For given IDFS lineage and time, fill an entire spin structure, select the sweep closest to the given azimuth, and return a pointer to a complete copy of that azimuthal slice. Use the options in paopts to determine if/how pitch angles are to be done. If so, the slice returned is the spin rebinned to pitch angle. Spin data is freed prior to return |
SDDAS_SHORT GetNPeaceSweeps( IDFS_LINEAGE *lngp, IDFS_TIME *btimep, IDFS_TIME *etimep, BIN_UNITS bin_units, PSD_UNITS psd_units, T_OR_F do_pa, int *nswps, PEACE_SWEEP ***swpppp) |
ALL_OKAY other IDFS return values Qpeace error codes |
Get all PEACE sweep data within times specified. Put them
each in a PEACE_SWEEP structure and return an array of pointers which
points to them. Each sweep structure includes its own copies of bin
boundaries and lineage. This module is self-contained and deals with
all IDFS calls. It returns the pointer to an array of sweep structure
pointers, and mallocs all the necessary internal storage required,
including the pointer array. Inputs are self-evident from their
declarations Output is malloced and filled pointer array (and the
nsweeps, sweep structures to which they point!). If virtual
instrument is "PAD", this routine calls GetNPeacePADs. Combines data
from more than one idfs file by calling the lower level routine
GetN1PeaceSweeps multiple times. |
SDDAS_SHORT
nsweeps2QiCDFContents( PEACE_SWEEP **swppp, int nswps, QiCDFContents **QiCDFp); |
ALL_OKAY PEACE_SWEEPS_SIZE_DIFFER PEACE_SWEEPS_EXPORT_ERROR |
Take tne nswps pointed to by swppp (e.g., as received from
GetNPeaceSweeps) and fill a QiCDFContents structure with them, from
which the data may be ingested into other software (e.g., QSAS) or
exported to flat or CDF files. Uses QM import/export modules, as used
by QSAS and Qtran. Creates the QiCDFContents object and all internal
structures/arrays. Calls subsidiary functions nswps2CDF_... to deal
with metadata and the various sweep bins, psd arrays, etc. (see Qsweep_spin.h and .c code for
details). QiFreeCDFContentsObj(QiCDF) from qie module to release all memory. QiWrite... routines can be used the CDFContents object to write to CDF or flat files. |
SDDAS_SHORT init_spin3d( PEACE_SPIN3D *spin_dp, IDFS_LINEAGE *lngp, struct idf_data *idfp, SDDAS_ULONG dkey, int *n_sens, int *n_lev ) |
PEACE3D_ERROR ALL_OKAY |
initialise info in spin3d structure by reading some data. In
particular: spin_dp->tspin spin period in secs spin_dp->n_swp sweeps per spin spin_dp->btime to actual start of spin n_sen to number of sensors n_lev to number of levels File needs to be opened and positioned prior to call (see init_idf_file). On return, the file is position to the start of the NEXT spin (this cures some re-positioning problems; use idfs time routines if necessary to adjust start time prior to opening file). |
float
sweep_duration_calculator( IDFS_TIME *swpstart, int n) |
-1.0 on error Sweep start->start in secs |
Take n successive sweep start times, and calculate the nominal time from the beginning of one sweep to the next by throwing away the min and max values and averaging the rest. Necessary since sweeps at spin start are forced in time, so not regularly spaced from preceding. |
void
print_peace_spin_info( PEACE_SPIN3D *spinp ) |
Stdout print of spin start, end, period, and number of sweeps/spin | |
SDDAS_SHORT
malloc_spin_sweep( PEACE_SPIN3D *spinp, int n_sen, int n_lev, T_or_F do_pa ) |
ALL_OKAY or PEACE3D_ERROR |
Malloc spin and sweeps for a single spin. Specifically,
malloc: n_swp PEACE_SWEEP structures thlo, thhi arrays for theta limits: only 1 set for all sweeps elo, ehi arrays for energy limits; only 1 set for all sweeps lineage 1 structure for all sweeps n_swp psd arrays of n_lev x n_sen size Also set n_lev and n_sen inside all PEACE_SWEEP structures. If do_pa=QPTRUE mallocs n_swp pa arrays of n_lev x n_sen. Note: The PEACE_SPIN3D structure MUST be declared in calling routine. It is not malloced here. See free_spin_data. |
PEACE_SPIN3D
*copy_spin (PEACE_SPIN3D *spin) |
pointer to full copy of spin or NULL |
Makes a full copy using malloc_spin_sweep and carefully copies
contents. |
SDDAS_SHORT free_spin_data ( PEACE_SPIN3D *spinp ) |
ALL_OKAY | Frees up all memory malloced by malloc_spin_sweep routine. Does NOT free the PEACE_SPIN3D structure itself. |
SDDAS_SHORT free_n_spins( PEACE_SPIN3D **spinpp, int nspins) |
ALL_OKAY | Frees up all memory in nspins spin structures by successive calles to free_spin_data. AND by freeing the spin structures. |
SDDAS_SHORT fill_spin3d ( PEACE_SPIN3D *spinp, IDFS_LINEAGE *lngp, struct idf_data *idfp, SDDAS_ULONG dkey, BIN_UNITS bin_units, PSD_UNITS psd_units, PHI_ZERO_FRAME phi_frame, T_OR_F do_pa ) |
return value of fill_sweep PEACE3D_INCOMPLETE_SPIN or ALL_OKAY |
Fill spin structure by filling sweeps. Use 1st sweep in spin
to fill energy level and theta bins. All sweeps share the same energy
and theta arrays. Prior to calling this, the idf file needs to be opened and positioned (see init_idf_file and init_spin3d), spinp structure needs to have internal arrays malloced (see malloc_spin_sweep). PEACE_TZERO is the only phi_frame currently recognised. Some checks are made for incomplete spins, inconsistent timings and the like, with errors or warning messages as appropriate. All arguments are INPUTS. |
int find_az_sweep ( PEACE_SPIN3D *spinp, float az ) |
index of sweep within spin containing the given azimuth -1 if fails |
Find the azimuthal slice in spinp which contains (or is closest to if the az falls in a fly-back region) the input azimuthal angle in degrees. Az is in PEACE (t_zero) coordinates. The algorithm rolls over 360->0 if necessary. |