STEP_VIRT

A virtual model of the STEP detector array in python. The class STEP_VIRT contains the geometry and a frame of the detector. The script is based on virtual_detector.py by Lars Berger. Furthermore, the class STEP_DATA combines the STEP data files to a useful data product and contains functions to work on this data. A time series of the mean energy seen by each pixel can be calculated. Furthermore a pitch angle correction can be applied. The class is based on the script STEP.py and uses modified versions of load_nom_II.py, mag.py and plot_nom_II.py, all originally written by Lars.

Coordinate system (detector reference frame (DRF)):

• X: Axis through center of STEP (i.e. Pixel 8) with orientation from pinhole to detector array (0,0,0 = center of Pinhole)
• Y: from center to background pixel
• Z: completes the right-handed triade
• Phi: angle in the XY-plane
• Theta: angle in the XZ-plane
  The coordinate system is fixed within the spacecraft and the angles are relative to the coordinate system of the detector model, not the spacecraft reference frame (SRF). To transform from the SRF to the DRF a rotation by 35° counterclockwise is needed.

Pitch Angle Correction

To compare the mean energy seen by each pixel for a given point in time, the influences of the pitch angles must be corrected. Pitch angles are the angles between the magnetic field vector of the Interplanetary Magnetic Field and the particle velocity vector. The velocity vector can be split into a component parallel and perpendicular to the magnetic field. A sketch can be seen below. If a particle is injected at the sun, the time it needs to travel towards the STEP detector along the magnetic field depends on the velocity parallel to the magnetic field and therefore its energy as well as the pitch angle.

Particles with the same initial energy are seen later by pixels with larger pitch angles because the parallel velocity component is smaller. Under the made assumption that E=\frac{1}{2}mv^2 it holds that v\propto\sqrt{E}. We know that particles seen by different pixels at a given time must have the same parallel velocity component. Therefore, it holds that:

\frac{v_{\parallel,1}}{v_{\parallel,2}}=\frac{v_{\mathrm{total},1}}{v_{\mathrm{total},2}}\cdot\frac{\cos(\varphi_1)}{\cos(\varphi_2)}=\frac{\sqrt{E_1}}{\sqrt{E_2}}\cdot\frac{\cos(\varphi_1)}{\cos(\varphi_2)}=1\Rightarrow E_1=\frac{\cos^2(\varphi_2)}{\cos^2(\varphi_1)}\cdot E_2.

This equation can be used to remove the influences of the pitch angles for a comparison of the pixels. The energies depicted are not necessarily the correct particle energies anymore.

STEP_VIRT:

The parameter mag specifies whether the magnet or integral channel is created. This influences the position of the pinhole.

Functions:

• STEP_Frame(self): Creates a frame of the STEP detector array.
• pinhole_projection(self,phi,theta): Plots the projection of the pinhole onto the detector array for given angles phi and theta.
• hitfrac(self,phi,theta): Calculates the fraction of each detector covered by the projection of the pinhole for given angles phi and theta.
• pixel_array_2d(self): Plots pixel array in two dimensions with Stephan's underlying sketch.
• pitch_angle_particle_flow(self, ax, B, reference_frame = 'SRF'): Returns pitch angle for each pixel as scalar product of magnetic field vector and particle flow vector. Standard reference frame is 'SRF', but 'DRF' can also be chosen. Pitch angle is returned in radians and degrees. B has to be an numpy array.
• magnetic_field_vector(self,B,reference_frame = 'SRF'): Plots magnetic field vector into each pixel. Standard reference frame is 'SRF', but 'DRF' can also be chosen.
• pitch_angle_weighted(self,B,reference_frame = 'SRF'): Returns pitch angle for each pixel. Iteration over angles phi and theta. For each combination the unity velocity vector is calculated for the pitch angle calculation. Each pitch angle is then weighted with the covered fraction of the pixel to calculate an averaged pitch angle. The range over which phi and theta are iterated might need to be adjusted if the detector geometry is changed. Pitch angle is returned in radians and degrees. B has to be an numpy array.
• plot_pitch_angle(self,B,reference_frame='SRF',method='particle_flow',vmin=None,vmax=None): Calculates and plots pitch angle for each pixel. Takes magnetic field B and reference frame ('DRF' or 'SRF') as input. The method to calculate the pitch angles has to be specified ('weighted' or 'particle_flow').
• plot_vd_mag(self,B,reference_frame='SRF'): Plots detector geometry and pitch angles (both methods) for a given magnetic field B. Wrapper for magnetic_field_vector(), particle_flow_vectors() and plot_pitch_angle().

STEP_DATA:

If mag_path is given the magnetic field data is loaded. The reference frame can be specified using mag_frame. The variables are called B_R, B_T and B_N in the code, even if the spacecraft reference frame is used. This is an ancient relic from the past.

Functions (Only the ones relevant for data analysis are listed):

• plot_ts(self, res = '1min', head = -1, period = None, save = False, norm = False, overflow = True, esquare = False, grenzfunktion = None, alpha = 1.0): Plots time series of the chosen data. The parameter grenzfunktion can be used to exclude certain while using other functions. Returns figure and axes.
• calc_energy_means(self, res = '1min', head = -1, period = (dt.datetime(2021,12,4,13,30),dt.datetime(2021,12,4,16,30)), grenzfunktion=None, below=True, box_list=None, window_width=5, pixel_list=[i for i in range(1,16)], norm = 'tpmax', overflow = True, esquare = False): Calculates energy means and variance. Both grenzfunktion and below can be used to exclude data above or below the function. The parameter box_list is a relic from the past and should not be used. I guarantee for nothing. Returns both the means of the energy and the variance. Both means and variance contain their respective datetime as first element of the array.
• calc_corrected_energy_means(self, method = 'weighted', reference = 3, res = '1min', head = -1, period = (dt.datetime(2021,12,4,13,30),dt.datetime(2021,12,4,16,30)), grenzfunktion=None, below=True, window_width=5, pixel_list=[i for i in range(1,16)], norm = 'tpmax', overflow = True, esquare = False): Calculates the energy means corrected for the pitch angles. Only works properly if the magnetic field data is loaded in the spacecraft reference frame (srf). The calculation of the pitch angles via STEP_VIRT uses the geometry of the integral channel. The parameter method specifies which method is used by the virtual detector to calculate the pitch angles ('weighted' or 'particle_flow'). The pixel used as reference for comparison is given by the parameter reference.
• plot_energy_means(self, correction = None, res = '1min', head = -1, period = (dt.datetime(2021,12,4,13,30),dt.datetime(2021,12,4,16,30)), grenzfunktion=None, below=True, window_width=5, pixel_list=[i for i in range(1,16)], norm = 'tpmax', overflow = True, esquare = False): Plots the calculated energy means for each pixel. If correction is either 'weighted' or 'particle_flow', the corresponding method is used to correct the energies to the reference pixel. The corrected energies are plotted as well.
• plot_energy_means_hist(self, res = '1min', head = -1, period = (dt.datetime(2021,12,4,13,30),dt.datetime(2021,12,4,16,30)), grenzfunktion=None, below=True, window_width=5, pixel_list=[i for i in range(1,16)], norm = 'tpmax', overflow = True, esquare = False): Plots the calculated energy means for each pixel into the respective histograms. If correction is either 'weighted' or 'particle_flow', the corresponding method is used to correct the energies to the reference pixel. The corrected energies are plotted as well.

MAGdata:

This class is part of the script mag.py.

Functions:

• mag_ts(self,period=None): Plots a time series of the magnetic field components for a given period.