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              in an ipython session, the values of colorshift, dpi, and nframes will 
108              be saved between invocations of the script.  so will the colormap, 
109              plotting variable, and the most recent values of l, m, and n.  saving, 
110              however, must be turned on with very invocation.
111              
112              
113              Section 2: addharmonics.py
114              
115              as the name suggests, this script can plot sums of harmonics.  hence, 
116              the first thing you will be prompted to input is the number of modes.  
117              bear in mind that the more you specify the slower the script will run.  
118              you will then be prompted to enter the l, m, and n of the modes you wish 
119              to add.  as before, you may enter 'q' at any time to quit or 'c' to 
120              change plotting parameters.  once you close the plot window, you will 
121              enter a loop allowing you to change plotting parameters or save frames 
122              to disk.  that is, to enter a new combination of modes you will have to 
123              run the script again.
124              
125              this script also has an additional input parameter, freqscale.  this is 
126              the floating point value by which to multiply the frequencies of the 
127 tplarson 1.1 modes.  these frequencies come from a model.  since they are given in 
128              units of millihertz and the sun's peak acoustic power occurs at about 3 mHz, 
129              the default value of freqscale is 1/3 .  to 
130              see the sum evolve further in time, increase freqscale.  you may want to 
131              simultaneously increase nframes.
132              
133              when we evolve the sum in time for the animation, it may so happen that a 
134              frame will exceed the data range of the first frame, which is what we use 
135              by default to set the color scaling.  by setting colorshift=2, you can tell 
136              the script to scan through the frames ahead of time and set the range 
137              of the color scale accordingly.  however, the default setting would only result 
138              in some areas of the image being saturated, and this may be perfectly acceptable 
139              for many purposes.
140              
141              another difference is that the value of n is used to compute all 
142              plotting variables, because the modes are added together according to 
143              their relative surface magnitudes, which are given by a model.  also 
144              note that because we are plotting velocity, the amplitude of each mode 
145              is the amplitude of the displacement eigenfunction scaled by the 
146              frequency.
147              
148 tplarson 1.1 finally, note that if you save the output, the files will be labelled 
149              only be the final mode you entered.
150              
151              
152              Section 3: drawradial.py and addradial.py
153              
154              this script and the next plot interior views of the sun.  specifically, 
155              they plot the amplitudes of modes on the radius-theta plane, which is to 
156              say a plane containing the line of the sun's rotation axis.  to do so, 
157              they must read the radial eigenfunctions from a model, which has been 
158              computed by numerically solving a system of differential equations. this 
159              model can be downloaded from http://solar-center.stanford.edu/SoSH/#mods 
160              and you should unpack it in your "sosh" directory.
161              
162              these scripts no longer plot the modal velocity, but rather the velocity 
163              scaled by the square root of the background density.  this is for two 
164              reasons.  firstly, since the velocities drop off rapidly with depth 
165              while the density increases rapidly, the quantity plotted shows visible 
166              variations throughout the interior.  secondly, the square of this scaled 
167              velocity is actually equal to the energy density of the mode.
168              
169 tplarson 1.1 finally, these scripts take another input parameter, rsurf, with a 
170              default value of 1.0 .  you may specify a lower value to truncate the 
171              plots below the solar surface, which may be desirable if you find a plot 
172              dominated by the amplitude at the surface.
173              
174