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 .
8 Section 1: drawharmonics.py
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.
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
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:
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).
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:
47 Vmag - magnitude of the total velocity.
48 Vsq - square of total velocity, which is proportional to energy density.
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.
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.
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
68 many other parameters may be specified when the script is called. these
69 are the following:
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.
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.
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.
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.
93 dpi - sets the resolution of the output images in "dots per inch".
94 defaults to 300.
96 nframes - number of frames in the animation, defaults to 64.
98 figsize - size of plotting window, defaults to 5.
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.
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.
113 Section 2: addharmonics.py
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.
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.
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.
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
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.
152 Section 3: drawradial.py and addradial.py
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.
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.
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.