1 tplarson 1.1 
  2              this file provides quick instructions for using scripts in the SoshPy 
  3              Visualization Package, which was written to provide graphics to 
  4              accompany the Sonification of Solar Harmonics (SoSH) Tool.  full 
  5              documentation can be found in instructions_visual.txt .
  6              
  7              
  8              Section 1: drawharmonics.py
  9              
 10              the simplest of these scripts is drawharmonics.py , and in its simplest 
 11              invocation it can be run either at the command line with only "python 
 12              drawharmonics.py" or in an ipython session with "run drawharmonics".  in 
 13              both cases you will then be prompted to enter a single mode's spherical 
 14              harmonic degree (l), its azimuthal order (m), and its radial order (n), 
 15              although this last integer will only be used when displaying certain 
 16              variables.  by default, the scripts will plot the radial component of 
 17              the mode's velocity, in which case n is unused.  after the mode is 
 18              calcuated, the script will display an animation of the mode on the solar 
 19              surface.  once you close the plot window, you will be prompted to enter 
 20              another mode's l, m, and n.  to quit the script, enter 'q' at any time.
 21              
 22 tplarson 1.1 of course the detailed behavior of the script can be changed with a 
 23              variety of options, some of which can be specified when the script is 
 24              called, and some of which can be specified interactively.  to use the 
 25              latter functionality, you may enter 'c' at any time to change a plotting 
 26              parameter.  you will first be given the opportunity to change the 
 27              colormap.  the default is 'seismic'.  you may enter 'l' to print a list 
 28              of preinstalled colormaps, along with the colormap currently in use.  
 29              you may use your own colormap if you have registered it with 
 30              cm.register_colormap().  simply hit enter to retain the current 
 31              colormap.
 32              
 33              you will then be prompted to enter a plotting variable.  again, you may 
 34              enter 'l' to list options along with the variable currently in use.  the 
 35              options are the following six:
 36              
 37              Vr - radial or vertical component of velocity.
 38              Vt - latitudinal or theta component.
 39              Vp - longitudinal or phi component.
 40              Vh - horizontal component, = sqrt(Vt^2+Vp^2).
 41              
 42              so far, we have not needed the value of n.  for surface plots such as 
 43 tplarson 1.1 these, the value of n only serves to define the ratio of the vertical 
 44              component to the horizontal components of the velocity.  hence, n is 
 45              only used to determine the total velocity:
 46              
 47              Vmag - magnitude of the total velocity. 
 48              Vsq - square of total velocity, which is proportional to energy density.
 49              
 50              note that Vr, Vt, and Vp are signed values whereas Vh, Vmag, and Vsq are 
 51              unsigned.  also, for the large majority of modes, the vertical component 
 52              at the surface will be much larger than the horizontal component.
 53              
 54              finally, you have the option to save every frame of the animation as a 
 55              png file.  entering anything other than 'y' turns saving off.  these 
 56              files will be written into a subdirectory of the "png_out" directory.  
 57              you may subsequently use ffmpeg to render them as a single video file, 
 58              such as an mp4 or gif.
 59              
 60              you will now be returned to the query for l, m, and n.  if you simply 
 61              hit enter, the value from the previous iteration will be used.  hence, 
 62              if you simply want to see what the previous mode looks like with the new 
 63              colormap for instance, just hit enter three times.  or, for example, to 
 64 tplarson 1.1 save the mode you are currently looking at, close the plot window, enter 
 65              'c' and follow the prompts to turn on saving, then hit enter three 
 66              times.
 67              
 68              many other parameters may be specified when the script is called.  these 
 69              are the following:
 70              
 71              pixels - specifies the resolution of the animation by giving the number 
 72                       of pixels in both the x and y directions, so the total number 
 73                       of pixels will be pixels^2.  default is 1000.
 74              
 75              bangle - tilt of the solar rotation axis towards the observer in degrees.  
 76                       the sign appears to be reversed because python plots images 
 77                       "upside down".  default is 30.
 78              
 79              note: the function which maps pixels to locations on the sphere, 
 80              sosh.image2sphere(), has two more parameters that affect the appearance 
 81              of the image.  the first is pangle, which specifies the tilt of the 
 82              solar rotation axis left and right, default 0.  the other is distobs, 
 83              which gives the observer distance in solar radii, default 220.  this 
 84              value can be changed to zoom in and out of the image.  to use different 
 85 tplarson 1.1 values for these two parameters you will need to edit the script.
 86              
 87              colorshift - set to zero to use colormaps with default scaling.  for the 
 88                       signed quantities, this could result in the value of zero 
 89                       not falling in the center of the colormap, giving unexpected 
 90                       results.  set colorshift=1 (the default) to adjust the scaling 
 91                       for those quantities.
 92              
 93              dpi -    sets the resolution of the output images in "dots per inch".
 94                       defaults to 300.
 95              
 96              nframes - number of frames in the animation, defaults to 64.
 97              
 98              figsize - size of plotting window, defaults to 5.
 99              
100              animate - set to zero to plot a still image instead of an animation.  
101                       if saving is turned on, only a single png will be written. 
102                       defaults to 1. 
103              
104              show -   set to zero to turn off image display.  typically useful only 
105                       if you are writing images to disk.
106 tplarson 1.1 

107 tplarson 1.2 in an ipython session, the colormap and plotting variable will be saved 
108              between invocations of the script, as will the most recent values of l, 
109              m, and n.  saving, however, must be turned on with very invocation.

110 tplarson 1.1 
111              
112              Section 2: addharmonics.py
113              
114              as the name suggests, this script can plot sums of harmonics.  hence, 
115              the first thing you will be prompted to input is the number of modes.  
116              bear in mind that the more you specify the slower the script will run.  
117              you will then be prompted to enter the l, m, and n of the modes you wish 
118              to add.  as before, you may enter 'q' at any time to quit or 'c' to 
119              change plotting parameters.  once you close the plot window, you will 
120              enter a loop allowing you to change plotting parameters or save frames 
121              to disk.  that is, to enter a new combination of modes you will have to 
122              run the script again.
123              
124              this script also has an additional input parameter, freqscale.  this is 
125              the floating point value by which to multiply the frequencies of the 
126              modes.  these frequencies come from a model.  since they are given in 

127 tplarson 1.2 units of millihertz and the sun's peak acoustic power occurs at about 3 
128              mHz, the default value of freqscale is 1/3 .  to see the sum evolve 
129              further in time, increase freqscale.  you may want to simultaneously 
130              increase nframes.
131              
132              when we evolve the sum in time for the animation, it may so happen that 
133              a frame will exceed the data range of the first frame, which is what we 
134              use by default to set the color scaling.  by setting colorshift=2, you 
135              can tell the script to scan through the frames ahead of time and set the 
136              range of the color scale accordingly.  however, the default setting 
137              would only result in some areas of the image being saturated, and this 
138              may be perfectly acceptable for many purposes.

139 tplarson 1.1 
140              another difference is that the value of n is used to compute all 
141              plotting variables, because the modes are added together according to 
142              their relative surface magnitudes, which are given by a model.  also 
143              note that because we are plotting velocity, the amplitude of each mode 
144              is the amplitude of the displacement eigenfunction scaled by the 
145              frequency.
146              
147              finally, note that if you save the output, the files will be labelled 
148              only be the final mode you entered.
149              
150              
151              Section 3: drawradial.py and addradial.py
152              
153              this script and the next plot interior views of the sun.  specifically, 
154              they plot the amplitudes of modes on the radius-theta plane, which is to 
155              say a plane containing the line of the sun's rotation axis.  to do so, 
156              they must read the radial eigenfunctions from a model, which has been 
157              computed by numerically solving a system of differential equations. this 
158              model can be downloaded from http://solar-center.stanford.edu/SoSH/#mods 
159              and you should unpack it in your "sosh" directory.
160 tplarson 1.1 
161              these scripts no longer plot the modal velocity, but rather the velocity 
162              scaled by the square root of the background density.  this is for two 
163              reasons.  firstly, since the velocities drop off rapidly with depth 
164              while the density increases rapidly, the quantity plotted shows visible 
165              variations throughout the interior.  secondly, the square of this scaled 
166              velocity is actually equal to the energy density of the mode.
167              
168              finally, these scripts take another input parameter, rsurf, with a 
169              default value of 1.0 .  you may specify a lower value to truncate the 
170              plots below the solar surface, which may be desirable if you find a plot 
171              dominated by the amplitude at the surface.
172              
173