Return to quickstart_visual.txt CVS log

Up to [Development] / JSOC / proj / globalhs / sosh

new versions

this file provides quick instructions for using scripts in the SoshPy 
Visualization Package, which was written to provide graphics to 
accompany the Sonification of Solar Harmonics (SoSH) Tool.  full 
documentation can be found in instructions_visual.txt .


Section 1: drawharmonics.py

the simplest of these scripts is drawharmonics.py , and in its simplest 
invocation it can be run either at the command line with only "python 
drawharmonics.py" or in an ipython session with "run drawharmonics".  in 
both cases you will then be prompted to enter a single mode's spherical 
harmonic degree (l), its azimuthal order (m), and its radial order (n), 
although this last integer will only be used when displaying certain 
variables.  by default, the scripts will plot the radial component of 
the mode's velocity, in which case n is unused.  after the mode is 
calcuated, the script will display an animation of the mode on the solar 
surface.  once you close the plot window, you will be prompted to enter 
another mode's l, m, and n.  to quit the script, enter 'q' at any time.

of course the detailed behavior of the script can be changed with a 
variety of options, some of which can be specified when the script is 
called, and some of which can be specified interactively.  to use the 
latter functionality, you may enter 'c' at any time to change a plotting 
parameter.  you will first be given the opportunity to change the 
colormap.  the default is 'seismic'.  you may enter 'l' to print a list 
of preinstalled colormaps, along with the colormap currently in use.  
you may use your own colormap if you have registered it with 
cm.register_colormap().  simply hit enter to retain the current 
colormap.

you will then be prompted to enter a plotting variable.  again, you may 
enter 'l' to list options along with the variable currently in use.  the 
options are the following six:

Vr - radial or vertical component of velocity.
Vt - latitudinal or theta component.
Vp - longitudinal or phi component.
Vh - horizontal component, = sqrt(Vt^2+Vp^2).

so far, we have not needed the value of n.  for surface plots such as 
these, the value of n only serves to define the ratio of the vertical 
component to the horizontal components of the velocity.  hence, n is 
only used to determine the total velocity:

Vmag - magnitude of the total velocity. 
Vsq - square of total velocity, which is proportional to energy density.

note that Vr, Vt, and Vp are signed values whereas Vh, Vmag, and Vsq are 
unsigned.  also, for the large majority of modes, the vertical component 
at the surface will be much larger than the horizontal component.

finally, you have the option to save every frame of the animation as a 
png file.  entering anything other than 'y' turns saving off.  these 
files will be written into a subdirectory of the "png_out" directory.  
you may subsequently use ffmpeg to render them as a single video file, 
such as an mp4 or gif.

you will now be returned to the query for l, m, and n.  if you simply 
hit enter, the value from the previous iteration will be used.  hence, 
if you simply want to see what the previous mode looks like with the new 
colormap for instance, just hit enter three times.  or, for example, to 
save the mode you are currently looking at, close the plot window, enter 
'c' and follow the prompts to turn on saving, then hit enter three 
times.

many other parameters may be specified when the script is called.  these 
are the following:

pixels - specifies the resolution of the animation by giving the number 
         of pixels in both the x and y directions, so the total number 
         of pixels will be pixels^2.  default is 1000.

bangle - tilt of the solar rotation axis towards the observer in degrees.  
         the sign appears to be reversed because python plots images 
         "upside down".  default is 30.

note: the function which maps pixels to locations on the sphere, 
sosh.image2sphere(), has two more parameters that affect the appearance 
of the image.  the first is pangle, which specifies the tilt of the 
solar rotation axis left and right, default 0.  the other is distobs, 
which gives the observer distance in solar radii, default 220.  this 
value can be changed to zoom in and out of the image.  to use different 
values for these two parameters you will need to edit the script.

colorshift - set to zero to use colormaps with default scaling.  for the 
         signed quantities, this could result in the value of zero 
         not falling in the center of the colormap, giving unexpected 
         results.  set colorshift=1 (the default) to adjust the scaling 
         for those quantities.

dpi -    sets the resolution of the output images in "dots per inch".
         defaults to 300.

nframes - number of frames in the animation, defaults to 64.

figsize - size of plotting window, defaults to 5.

animate - set to zero to plot a still image instead of an animation.  
         if saving is turned on, only a single png will be written. 
         defaults to 1. 

show -   set to zero to turn off image display.  typically useful only 
         if you are writing images to disk.

in an ipython session, the values of colorshift, dpi, and nframes will 
be saved between invocations of the script.  so will the colormap, 
plotting variable, and the most recent values of l, m, and n.  saving, 
however, must be turned on with very invocation.


Section 2: addharmonics.py

as the name suggests, this script can plot sums of harmonics.  hence, 
the first thing you will be prompted to input is the number of modes.  
bear in mind that the more you specify the slower the script will run.  
you will then be prompted to enter the l, m, and n of the modes you wish 
to add.  as before, you may enter 'q' at any time to quit or 'c' to 
change plotting parameters.  once you close the plot window, you will 
enter a loop allowing you to change plotting parameters or save frames 
to disk.  that is, to enter a new combination of modes you will have to 
run the script again.

this script also has an additional input parameter, freqscale.  this is 
the floating point value by which to multiply the frequencies of the 
modes.  these frequencies come from a model.  since they are given in 
units of millihertz and the sun's peak acoustic power occurs at about 3 mHz, 
the default value of freqscale is 1/3 .  to 
see the sum evolve further in time, increase freqscale.  you may want to 
simultaneously increase nframes.

when we evolve the sum in time for the animation, it may so happen that a 
frame will exceed the data range of the first frame, which is what we use 
by default to set the color scaling.  by setting colorshift=2, you can tell 
the script to scan through the frames ahead of time and set the range 
of the color scale accordingly.  however, the default setting would only result 
in some areas of the image being saturated, and this may be perfectly acceptable 
for many purposes.

another difference is that the value of n is used to compute all 
plotting variables, because the modes are added together according to 
their relative surface magnitudes, which are given by a model.  also 
note that because we are plotting velocity, the amplitude of each mode 
is the amplitude of the displacement eigenfunction scaled by the 
frequency.

finally, note that if you save the output, the files will be labelled 
only be the final mode you entered.


Section 3: drawradial.py and addradial.py

this script and the next plot interior views of the sun.  specifically, 
they plot the amplitudes of modes on the radius-theta plane, which is to 
say a plane containing the line of the sun's rotation axis.  to do so, 
they must read the radial eigenfunctions from a model, which has been 
computed by numerically solving a system of differential equations. this 
model can be downloaded from http://solar-center.stanford.edu/SoSH/#mods 
and you should unpack it in your "sosh" directory.

these scripts no longer plot the modal velocity, but rather the velocity 
scaled by the square root of the background density.  this is for two 
reasons.  firstly, since the velocities drop off rapidly with depth 
while the density increases rapidly, the quantity plotted shows visible 
variations throughout the interior.  secondly, the square of this scaled 
velocity is actually equal to the energy density of the mode.

finally, these scripts take another input parameter, rsurf, with a 
default value of 1.0 .  you may specify a lower value to truncate the 
plots below the solar surface, which may be desirable if you find a plot 
dominated by the amplitude at the surface.