Package: vsmodel
vsmodelA simple implementation of the Volland-Stern electric field model (Volland, 1973; Stern, 1975).The electric field model here is only defined in the equatorial plane around the Earth, where any vertical component returns is filled with zeros.There are two implementations of this model: one is based on that used by Zhao et al. 2017 which uses the Maynard and Chen 1975 relation between theKpindex and the convection electric field; the other uses the work of Goldstein et al 2005 which separates the convection electric field into two components.InstallationInstall using this Github repo:gitclonehttps://github.com/mattkjames7/vsmodelcdvsmodelthen either usingsetup.py:python3setup.pyinstall--useror by creating a wheel:python3setup.pybdist_wheel
pip3installdist/vsmodel-x.x.x-py3-none-any.whl--userwherex.x.xshould be replaced with the current version number.Alternatively, install usingpip3:pip3installvsmodel--userUsageThere are two functions which can be used to calculate the model electric field, one using cylindrical coordinates and the other using the Cartesian Solar Magnetic (SM) coordinate system:importvsmodel##### The simple model using Maynard and Chen #####the Cartesian modelEx,Ey,Ez=vsmodel.ModelCart(x,y,Kp)#the cylindrical modelEr,Ep,Ez=vsmodel.ModelE(r,phi,Kp)#### The Goldstein et al 2005 version #####the Cartesian model, either by providing solar wind speed (Vsw) and IMF Bz (Bz), or the equivalent E field (Esw)Ex,Ey,Ez=vsmodel.ModelCart(x,y,Kp,Vsw=Vsw,Bz=Bz)Ex,Ey,Ez=vsmodel.ModelCart(x,y,Kp,Esw=Esw)#the cylindrical modelEr,Ep,Ez=vsmodel.ModelE(r,phi,Kp,Vsw=Vsw,Bz=Bz)Er,Ep,Ez=vsmodel.ModelE(r,phi,Kp,Esw=Esw)whereKpis theKpindex;xandyare the Cartesian coordinates in the magnetic equatorial plane (in RE, where RE=6378 km);randphiare the equatorial radial distance from the centre of the Earth (inRE) and the azimuthal angle (phi=0.0 at noon, in radians). Both functions return the electric field in units of mV/mPlotting the modelThe functionvsmodel.PlotModelEqwill plot the V-S model potential, electric field, a dipole magnetic field and theExBvelocity in the equatorial plane, e.g.:importvsmodelimportmatplotlib.pyplotasplt#The simple modelplt.figure(figsize=(9,8))ax0=vsmodel.PlotModelEq('E',Kp=1.0,maps=[2,2,0,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax1=vsmodel.PlotModelEq('E',Kp=5.0,maps=[2,2,1,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax2=vsmodel.PlotModelEq('V',Kp=1.0,maps=[2,2,0,1],fig=plt,scale=[100.0,100000.0])ax3=vsmodel.PlotModelEq('V',Kp=5.0,maps=[2,2,1,1],fig=plt,scale=[100.0,100000.0])ax0.set_title('$K_p=1$')ax2.set_title('$K_p=1$')ax3.set_title('$K_p=5$')ax1.set_title('$K_p=5$')plt.tight_layout()#The Goldstein modelplt.figure(figsize=(9,8))ax0=vsmodel.PlotModelEq('E',Kp=1.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,0,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax1=vsmodel.PlotModelEq('E',Kp=5.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,1,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax2=vsmodel.PlotModelEq('V',Kp=1.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,0,1],fig=plt,scale=[100.0,10000.0])ax3=vsmodel.PlotModelEq('V',Kp=5.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,1,1],fig=plt,scale=[100.0,10000.0])ax0.set_title('$K_p=1$; $E_{sw}=-1$ mV m$^{-1}$')ax2.set_title('$K_p=1$; $E_{sw}=-1$ mV m$^{-1}$')ax3.set_title('$K_p=5$; $E_{sw}=-1$ mV m$^{-1}$')ax1.set_title('$K_p=5$; $E_{sw}=-1$ mV m$^{-1}$')plt.tight_layout()Which should produce this:andAlternatively, we can plot the model vectors as a field of arrows:importvsmodelimportmatplotlib.pyplotasplt#The simple modelplt.figure(figsize=(9,8))ax0=vsmodel.PlotVectorEq('E',Kp=1.0,maps=[2,2,0,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax1=vsmodel.PlotVectorEq('E',Kp=5.0,maps=[2,2,1,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax2=vsmodel.PlotVectorEq('V',Kp=1.0,maps=[2,2,0,1],fig=plt,scale=[100.0,100000.0])ax3=vsmodel.PlotVectorEq('V',Kp=5.0,maps=[2,2,1,1],fig=plt,scale=[100.0,100000.0])plt.tight_layout()#The Goldstein modelplt.figure(figsize=(9,8))ax0=vsmodel.PlotVectorEq('E',Kp=1.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,0,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax1=vsmodel.PlotVectorEq('E',Kp=5.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,1,0],fig=plt,fmt='%4.2f',scale=[0.01,10.0])ax2=vsmodel.PlotVectorEq('V',Kp=1.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,0,1],fig=plt,scale=[100.0,100000.0])ax3=vsmodel.PlotVectorEq('V',Kp=5.0,Vsw=-400.0,Bz=-2.5,maps=[2,2,1,1],fig=plt,scale=[100.0,100000.0])plt.tight_layout()which produces:andNotes on the coordinate systemsSMThe Solar Magnetic (SM) coordinate system is defined such that thez-axis is aligned with the Earth's magnetic dipole; thex-axis lies in the plane which contains both the Earth-Sun line and the dipole axis (thex-axis points close-ish towards the Sun); they-axis completes the right-handed set and points approximately in the opposite direction to that of the Earth's orbital motion around the Sun.As this model is defined only in the equatorial plane, there is no input for thezcoordinate; also there is not azcomponent to the model soEzis filled with zeros.CylindricalThe cylindrical coordinates used are defined such thatris the radial distance from thez-axis andphiis the azimuthal angle.zis not used as an input because the model is confined to the equatorial plane. The outputsEr,EpandEzcorrespond to the radial, azimuthal and vertical (z) components of the model electric field. As with the Cartesian version of the model, there is no vertical component to the electric field model, so theEzcomponent is filled with zeros.DerivationThe derivation of the model equations can be foundhere- if there any mistakes, please file a bug report, thanks!ReferencesGoldstein, J., Burch, J. L., and Sandel, B. R. (2005), Magnetospheric model of subauroral polarization stream,J. Geophys. Res., 110, A09222, doi:10.1029/2005JA011135.Maynard, N. C., and Chen, A. J. (1975), Isolated cold plasma regions: Observations and their relation to possible production mechanisms,J. Geophys. Res., 80( 7), 1009– 1013, doi:10.1029/JA080i007p01009.Stern, D. P. (1975), The motion of a proton in the equatorial magnetosphere,J. Geophys. Res., 80( 4), 595– 599, doi:10.1029/JA080i004p00595.Volland, H. (1973), A semiempirical model of large‐scale magnetospheric electric fields,J. Geophys. Res., 78( 1), 171– 180, doi:10.1029/JA078i001p00171.Zhao, H., Baker, D. N., Califf, S., Li, X., Jaynes, A. N., Leonard, T., … Spence, H. E. (2017). Van Allen probes measurements of energetic particle deep penetration into the low L region (L< 4) during the storm on 8 April 2016.Journal of Geophysical Research: Space Physics, 122, 12,140– 12,152.https://doi.org/10.1002/2017JA024558