Difference between revisions of "User:Tohline/IVAJ/Levels2and3"

From VistrailsWiki
Jump to navigation Jump to search
(Replaced entire page with "Level 1" text so that all Level 1 links are preserved; then inserted early draft of "Mashup App" subsection)
 
(15 intermediate revisions by 2 users not shown)
Line 21: Line 21:
LSU's astrophysics group has begun to incorporate [http://www.vistrails.org VisTrails] into its arsenal of scientific visualization and data analysis tools.  [http://www.vistrails.org VisTrails] primarily interested the group a few years ago because it provides a user-friendly workflow interface to the [http://www.vtk.org/ extensive VTK software library].  It also automatically tracks the provenance of data analysis efforts.  However, what most impresses us now is the ease with which [http://www.vistrails.org VisTrails] facilitates the insertion of home-grown analysis modules into an otherwise VTK-based workflow.  Taking advantage of this additional programming versatility, we have gained a greater appreciation of the role that visualization tools can play in the quantitative assessment of results from large-scale simulations.  In this article, we first describe the VTK-based workflow that we initially constructed in [http://www.vistrails.org VisTrails] to view streamlines within each binary mass-transfer simulation.  We then describe the Python module, whose insertion into this workflow has permitted us to identify values of key rotational frequencies associated with such flows.
LSU's astrophysics group has begun to incorporate [http://www.vistrails.org VisTrails] into its arsenal of scientific visualization and data analysis tools.  [http://www.vistrails.org VisTrails] primarily interested the group a few years ago because it provides a user-friendly workflow interface to the [http://www.vtk.org/ extensive VTK software library].  It also automatically tracks the provenance of data analysis efforts.  However, what most impresses us now is the ease with which [http://www.vistrails.org VisTrails] facilitates the insertion of home-grown analysis modules into an otherwise VTK-based workflow.  Taking advantage of this additional programming versatility, we have gained a greater appreciation of the role that visualization tools can play in the quantitative assessment of results from large-scale simulations.  In this article, we first describe the VTK-based workflow that we initially constructed in [http://www.vistrails.org VisTrails] to view streamlines within each binary mass-transfer simulation.  We then describe the Python module, whose insertion into this workflow has permitted us to identify values of key rotational frequencies associated with such flows.


==Mashup App==
<table width="95%" border=2 align="center" bgcolor="#000033" cellpadding=10>
 
This embedded VisMashup application serves as a replacement for Figure 1 and Figure 2 from the original, published version of this article [1].  Clicking on the App's "Provenance Explanation" tab displays an image of the VisTrails workflow and serves in place of the original Figure 1.  An interactive replacement for Figure 2 is revealed by clicking on the App's "Mashup" tab.
<div align="center">
<table border=1 cellpadding=8 width="95%">
<tr><td>
<tr><td>
<font color="darkgreen">Caption to Figure 1</font> ("Provenance Explanation" tab): Screenshot of the window within the VisTrails builder that displays user-defined visualization workflowsShown here is the customized workflow that is used to generate Figure 2.  The SwitchCoord module containing our customized Python script has been inserted into the workflow.
'''<font size="+1"color="darkblue">TERMINOLOGY</font>'''<br>
One well-defined characteristic of a binary star system is it orbital period, <math>P</math>.  If the stars are in circular orbit around one another, a binary system will appear to be stationary when viewed from a frame that's rotating with an angular frequency <math>\Omega_\mathrm{frame} = 2\pi/P</math>.  When modeling mass-transferring binary star systems, we've found it advantageous to perform each computational fluid dynamic (CFD) simulation on a cylindrical-coordinate grid that rotates with a frequency <math>\Omega_0 = 2\pi/P_0</math>, where <math>P_0</math> is the binary system's orbital period at the beginning of the simulation. As mass and angular momentum are transferred from one star to the other throughout the simulation, however, the binary system's orbital period &#150; and associated value of <math>\Omega_\mathrm{frame}</math> &#150; will varyAs explained in the main text, we used [http://www.vistrails.org VisTrails] to measure <math>\Delta\Omega = (\Omega_\mathrm{frame} - \Omega_0)</math> and, hence, the instantaneous orbital period <math>P = P_0/(1 + P_0 \Delta\Omega/2\pi)</math> at any time during a simulation.
</td></tr>
</td></tr>
</table>
</table>
</div>
 
==<font color="#0000DD">Base Workflow</font>==
 
Within [http://www.vistrails.org VisTrails], we initially selected various VTK-based modules to do the following, in sequence (see Figure 1):
*''Read simulation data.'' We used <font face="Courier">vtkPLOT3DReader</font> to read in one file containing the <math>(x, y, z)</math> coordinate locations of every vertex on our 3D cylindrical coordinate mesh and a separate file containing the fluid's mass-density (scalar) and momentum-density (3D vector) at every grid vertex.
*''Outline cylindrical domain boundary.'' As shown, we enlisted <font face="Courier">vtkStructuredGridOutlineFilter</font>, <font face="Courier">vtkPolyDataMapper</font>, and <font face="Courier">vtkActor</font>.
*''Define isodensity surfaces.'' We rendered two nested isodensity surfaces to outline high- (red) and low-density (blue) flow regions.  The <font face="Courier">Red_contour</font> and <font face="Courier">Blue_contour</font> module groups each contain <font face="Courier">vtkContourFilter</font>, <font face="Courier">vtkDataSetMapper</font>, <font face="Courier">vtkProperty</font>, and <font face="Courier">vtkActor</font>.
*''Draw streamlines.'' Each of eight separate <font face="Courier">Draw_Streamlines</font> module groups uses <font face="Courier">vtkStreamLine</font>, <font face="Courier">vtkTubeFilter</font>, <font face="Courier">vtkDataSetMapper</font>, <font face="Courier">vtkProperty</font>, <font face="Courier">vtkActor</font>, <font face="Courier">vtkSphereSource</font>, <font face="Courier">vtkPolyDataMapper</font>, and <font face="Courier">vtkLODActor</font> to trace an individual streamline within the flow.  Streamline lengths are set by feeding a common <font face="Courier">Propagation_Time</font> into all eight module groups.
 
[http://www.vistrails.org VisTrails] renders the output from the various workflow actors in a composite scene using <font face="Courier">vtkRenderer</font> as viewed by an observer located at a position that <font face="Courier">vtkCamera</font> specifies.  Finally, the module <font face="Courier">vtkCell</font> directs this scene to the VisTrails interactive spreadsheet.
 
In our initially constructed ''base workflow,'' [http://www.vistrails.org VisTrails] piped the 3D vector field representing the momentum density distribution from the <font face="Courier">vtkPLOT3DReader</font> module directly into each of the eight <font face="Courier">Draw_Streamline</font> module groups.  This base workflow &#8212; which [http://www.vistrails.org VisTrails] assembles using generically available <font face="Courier">vtk</font> modules &#8212; let us examine the behavior of streamlines in our binary mass-transfer simulations, but only from the frame of reference, <math>\Omega_0</math>, in which we originally performed each simulation (see Figure 2, with the parameter <font face="Courier">Omega_frame</font> = 0.00).


<!-- vistrail host="vistrails.sci.utah.edu" db="vistrails" vtid="11" version="1826" tag="" showspreadsheetonly="True"/ -->
<!-- vistrail host="vistrails.sci.utah.edu" db="vistrails" vtid="11" version="1826" tag="" showspreadsheetonly="True"/ -->
Line 36: Line 44:
<!--vistrail host="vistrails.sci.utah.edu" db="vistrails" vtid="19" version="1842" tag="" showspreadsheetonly="True"/-->
<!--vistrail host="vistrails.sci.utah.edu" db="vistrails" vtid="19" version="1842" tag="" showspreadsheetonly="True"/-->


<vismashup mid=19 showspreadsheetonly="True" />
<div align="center">
<div align="center">
<table border=1 cellpadding=8 width="95%">
<table cellpadding=5 border=3 bordercolor="purple" width="95%">
<tr><td align="center">
<font color="darkblue" size="+1"><b>
VisMashup containing<br/>
Figure 1 &amp; Figure 2<br />
</b></font>
(Click on relevant tab to switch between figures.)
</td></tr>
<tr><td>
<tr><td>
<font color="darkgreen">Caption to Figure 2</font> ("Mashup" tab):  Resulting rendered image generated by the VisTrails workflow displayed in Figure 1.
<vismashup mid=19 showspreadsheetonly="True" embedworkflow="True"/>
</td></tr>
</td></tr>
</table>
</div>


==<font color="#0000DD">Base Workflow</font>==
<tr><td align="left">
<font size="+1" color="black"><b>Figure 1</b></font>
Layout of the VisTrails workflow that is used to generate Figure 2. We constructed the base workflow (everything shown excluding the custom-built <font face="Courier">SwitchCoord</font> module and the <font face="Courier">Omega_frame</font> parameter specification) from standard VTK-based modules. A PDF document containing this figure can be obtained by clicking on the "Download Workflow" button.
</td></tr>


[[Image:Figure1_Tohline.jpg |border|center|600px|Figure 1. Screenshots of the window within the VisTrails builder that displays user-designed visualization workflows. (a = left panel) The base workflow we constructed from standard VTK-based modules.  (b = inset panel) A segment of the workflow that's hidden inside the <font face="Courier">Draw_Streamlines</font> group module. (c = right panel) The customized workflow we used to create Figure 2, in which we inserted the <font face="Courier">SwitchCoord</font> module containing our customized Python script into the base workflow.]]
<tr><td align="left">
<center>'''Figure 1:''' (scroll over image for caption)</center>
<font size="+1" color="black"><b>Figure 2</b></font>: 
An image generated by our customized [http://www.vistrails.org VisTrails] workflow using the indicated values of the three variable parameters, <font face="Courier">Omega_frame</font> <math>(= \Delta \Omega)</math>, <font face="Courier">rho_min</font>, and <font face="Courier">Propagation_time</font>. The 3D-rendered image displays eight equatorial-plane streamlines and a pair of isodensity surfaces (lower density surface colored blue; higher density surface colored red) that outline the structure of both stars as well as the connecting mass-transfer stream.  The propagation time is the same for all eight streamlines; along six streamlines, [http://www.vistrails.org VisTrails] carries out the integration in both directions from the location marked by a small colored sphere.  Streamlines are truncated prematurely if they enter a region in which the matter density drops below the value specified by <font face="Courier">rho_min</font>, measured as a fraction of the maximum density.  A new image will be generated by the VisTrails Wiki server (in accordance with the workflow shown in Figure 1) if the reader selects a different set of parameters and clicks the green "Update" button. Recommended parameter ranges:<br />
<div align="center">
0.0005 < <font face="courier">rho_min</font> < 0.05
<br />


Within [http://www.vistrails.org VisTrails], we initially selected various VTK-based modules to do the following, in sequence (see Figure 1a):
0.1 < <font face="courier">propagation_time</font> < 3.5
*''Read simulation data.'' We used <font face="Courier">vtkPLOT3DReader</font> to read in one file containing the <math>(x, y, z)</math> coordinate locations of every vertex on our 3D cylindrical coordinate mesh and a separate file containing the fluid's mass-density (scalar) and momentum-density (3D vector) at every grid vertex.
</div>
*''Outline cylindrical domain boundary.'' As shown, we enlisted <font face="Courier">vtkStructuredGridOutlineFilter</font>, <font face="Courier">vtkPolyDataMapper</font>, and <font face="Courier">vtkActor</font>.
*''Define isodensity surfaces.'' We rendered two nested isodensity surfaces to outline high- (red) and low-density (blue) flow regions.  The <font face="Courier">Red_contour</font> and <font face="Courier">Blue_contour</font> module groups each contain <font face="Courier">vtkContourFilter</font>, <font face="Courier">vtkDataSetMapper</font>, <font face="Courier">vtkProperty</font>, and <font face="Courier">vtkActor</font>.
*''Draw streamlines.'' As Figure 1b shows, each of the eight separate <font face="Courier">Draw_Streamlines</font> module groups uses <font face="Courier">vtkStreamLine</font>, <font face="Courier">vtkTubeFilter</font>, <font face="Courier">vtkDataSetMapper</font>, <font face="Courier">vtkProperty</font>, <font face="Courier">vtkActor</font>, <font face="Courier">vtkSphereSource</font>, <font face="Courier">vtkPolyDataMapper</font>, and <font face="Courier">vtkLODActor</font> to trace an individual streamline within the flow.  Streamline lengths are set by feeding a common <font face="Courier">Propagation_Time</font> into all eight module groups.


[http://www.vistrails.org VisTrails] renders the output from the various workflow actors in a composite scene using <font face="Courier">vtkRenderer</font> as viewed by an observer located at a position that <font face="Courier">vtkCamera</font> specifies.  Finally, the module <font face="Courier">vtkCell</font> directs this scene to the VisTrails interactive spreadsheet.
</td></tr>


In this initially constructed ''base workflow,'' [http://www.vistrails.org VisTrails] pipes the 3D vector field representing the momentum density distribution from the <font face="Courier">vtkPLOT3DReader</font> module directly into each of the eight <font face="Courier">Draw_Streamline</font> module groups. This base workflow &#8212; which [http://www.vistrails.org VisTrails] assembles using generically available <font face="Courier">vtk</font> modules &#8212; lets us examine the behavior of streamlines in our binary mass-transfer simulations, but only from the frame of reference, <math>\Omega_0</math>, in which we originally performed each simulation (see Figure 2b, labeled <math>\Delta\Omega = 0.00</math>).
<tr><td align="left">
<font size="+1" color="red"><b>Execute on my desktop</b></font>:  
[[Image:VisTrails_Install_icon.jpg|right|frameless|border|link=http://www.sci.utah.edu/~emanuele/movies/Stars.mov]] Clicking on Figure 2's red "Execute on my desktop" button will download the Figure 1 workflow to the reader's laptop/desktop system for local execution.  In order for this to work, VisTrails (version 1.4.2 or higher) must be installed on the reader's local system.  (For help installing VisTrails, click the icon shown here on the right, or view [http://www.youtube.com/watch?v=4oDXEjtYWJk&fmt=22 this YouTube video].) Note that two data files totaling > 100 MBytes will also be transferred for analysis on the local system, so the entire download may take 10 or more minutes, depending on the network connection.
</td></tr>


<table width="95%" border=2 align="center" bgcolor="#000033" cellpadding=10>
<tr><td>
'''<font size="+1"color="darkblue">TERMINOLOGY</font>'''<br>
One well-defined characteristic of a binary star system is it orbital period, <math>P</math>.  If the stars are in circular orbit around one another, a binary system will appear to be stationary when viewed from a frame that's rotating with an angular frequency <math>\Omega_\mathrm{frame} = 2\pi/P</math>.  When modeling mass-transferring binary star systems, we've found it advantageous to perform each computational fluid dynamic (CFD) simulation on a cylindrical-coordinate grid that rotates with a frequency <math>\Omega_0 = 2\pi/P_0</math>, where <math>P_0</math> is the binary system's orbital period at the beginning of the simulation.  As mass and angular momentum are transferred from one star to the other throughout the simulation, however, the binary system's orbital period &#150; and associated value of <math>\Omega_\mathrm{frame}</math> &#150; will vary.  As explained in the main text, we used [http://www.vistrails.org VisTrails] to measure <math>\Delta\Omega = (\Omega_\mathrm{frame} - \Omega_0)</math> and, hence, the instantaneous orbital period <math>P = P_0/(1 + P_0 \Delta\Omega/2\pi)</math> at any time during a simulation.
</td></tr>
</table>
</table>
</div>


==<font color="#0000DD">Customized Python Module</font>==
==<font color="#0000DD">Customized Python Module</font>==
To make it possible for us to examine the properties of binary mass-transfer flows from reference frames that have a range of different angular frequencies of rotation, <math>\Omega_\mathrm{frame}  = (\Omega_0 + \Delta\Omega)</math>, we wrote a Python-based module &#150; <font face="Courier">SwitchCoord</font> &#150; for insertion into the base [http://www.vistrails.org VisTrails] workflow.  Figure 1c shows our resulting customized [http://www.vistrails.org VisTrails] workflow; it differs very little from the base workflow.  The [http://www.vistrails.org/index.php/User:Tohline/CustomizedPythonModule#Sidebar sidebar] shows the complete Python source code from our customized module.  The code segment that performs the required ''physics analysis'' is short and straightforward.  In particular, the <font face="Courier">SwitchCoord</font> module performs the following operations at each grid vertex:
To make it possible for us to examine the properties of binary mass-transfer flows from reference frames that have a range of different angular frequencies of rotation, <math>\Omega_\mathrm{frame}  = (\Omega_0 + \Delta\Omega)</math>, we wrote a Python-based module &#150; <font face="Courier">SwitchCoord</font> &#150; for insertion into the base [http://www.vistrails.org VisTrails] workflow.  The [http://www.vistrails.org/index.php/User:Tohline/CustomizedPythonModule#Sidebar sidebar] shows the complete Python source code from our customized module.  The code segment that performs the required ''physics analysis'' is short and straightforward.  In particular, the <font face="Courier">SwitchCoord</font> module performs the following operations at each grid vertex:
* converts the <math>(x, y)</math> Cartesian to <math>(R, \phi)</math> cylindrical coordinates;
* converts the <math>(x, y)</math> Cartesian to <math>(R, \phi)</math> cylindrical coordinates;
* divides the momentum components by density to obtain the velocity components if the density is greater than <font face="Courier">minp</font> (otherwise, it sets the velocity components to zero);
* divides the momentum components by density to obtain the velocity components if the density is greater than <font face="Courier">minp</font> (otherwise, it sets the velocity components to zero);
Line 75: Line 90:
* normalizes the velocities to the maximum velocity <font face="Courier">maxnorm</font> found across the domain where densities are greater than <font face="Courier">minp</font>.
* normalizes the velocities to the maximum velocity <font face="Courier">maxnorm</font> found across the domain where densities are greater than <font face="Courier">minp</font>.


We designed the output ports on <font face="Courier">SwitchCoord</font> to provide access to the same type of structured arrays that <font face="Courier">vtkPLOT3DReader</font> generates.  But, in our customized [http://www.vistrails.org VisTrails] workflow, which includes <font face="Courier">SwitchCoord</font> (see Figure 1c), the 3D vector field that [http://www.vistrails.org VisTrails] pipes into each of the eight <font face="Courier">Draw_Streamline</font> module groups represents the fluid's velocity distribution as viewed from the rotating frame of reference that the floating-point scalar, <font face="Courier">Omega_frame</font>, specifies.
We designed the output ports on <font face="Courier">SwitchCoord</font> to provide access to the same type of structured arrays that <font face="Courier">vtkPLOT3DReader</font> generates.  But, in our customized [http://www.vistrails.org VisTrails] workflow, the 3D vector field that [http://www.vistrails.org VisTrails] pipes into each of the eight <font face="Courier">Draw_Streamline</font> module groups represents the fluid's velocity distribution as viewed from the rotating frame of reference that the floating-point scalar, <font face="Courier">Omega_frame</font>, specifies.


==<font color="#0000DD">Interpretation of Results</font>==
==<font color="#0000DD">Interpretation of Results</font>==


[[Image:Figure2_Tohline.jpg |border|center|600px|Figure 2.  Screenshot of the [http://www.vistrails.org VisTrails] spreadsheet after we used five different values of <font face="Courier">Omega_frame</font> <math>(\Delta \Omega)</math> to execute our customized workflow.  Each 3D-rendered image displays eight equatorial-plane streamlines and a pair of isodensity surfaces (lower density surface colored blue; higher density surface colored red) that outline the structure of both stars as well as the connecting mass-transfer stream.  The propagation time is the same for all eight streamlines; along six streamlines, [http://www.vistrails.org VisTrails] carries out the integration in both directions from the location marked by a small colored sphere.]]
Figure 2 displays a 3D rendering of the flow from one of our binary mass-transfer simulations as generated by our customized [http://www.vistrails.org VisTrails] workflow using the parameter values indicated beside the imageIn particular, the streamlines shown in the default image were generated assuming a frame rotation frequency given by <font face="Courier">Omega_frame</font> = <math>\Delta\Omega = -0.041.</math> Using the Figure 2 VisMashup App, images can be generated assuming four other values of the frame rotation frequency in the range <math> +0.02 \ge \Delta\Omega \ge -0.06.</math> By downloading and executing this workflow on a local laptop/desktop system (click the red "Execute on my desktop" button shown in Figure 2), the reader can zoom, pan, and interactively rotate any of these 3D-rendered scenes and explore a wider range of model parameter values.
<center>'''Figure 2''' (scroll over image for caption)</center>
 
Figure 2 displays 3D renderings of the flow from one of our binary mass-transfer simulations as generated by our customized [http://www.vistrails.org VisTrails] workflow.  We have generated images assuming five different frame rotation frequencies, as specified by <math>\Delta\Omega</math>.  Aside from labeling <math>\Delta\Omega</math> values under each image, we produced Figure 2 by simply taking a screenshot of the [http://www.vistrails.org VisTrails] interactive spreadsheetThe spreadsheet feature has proven to be extremely useful in this analysis because it facilitates the side-by-side comparison of scenes that [http://www.vistrails.org VisTrails] has rendered using different parameter values.  And, although we can't demonstrate it here in print, [http://www.vistrails.org VisTrails] lets users zoom, pan, and interactively rotate all 3D-rendered scenes simultaneously.


We'd like to determine which value of <math>\Delta\Omega</math> provides the best measure of the binary star system's true orbital period.  As expected, for all five choices of <math>\Delta\Omega</math>, we found the highest velocities (marked by the longest streamlines) along the relatively low-density mass-transfer stream that connects the two stars.  Material from the donor star (in the lower half of each rendered image in Figure 2) flows toward its stellar companion, reaching supersonic velocities before impacting the companion.  An oblique shock front &#150; whose location is delineated by kinks in the pink, blue, and orange streamlines &#150; terminates the component of motion perpendicular to the companion's surface.  Motion transverse to the shock becomes orbital motion in a thick, low-density disk that surrounds the companion star.
We'd like to determine which value of <math>\Delta\Omega</math> provides the best measure of the binary star system's true orbital period.  For all five choices of <math>\Delta\Omega</math> identified by the Figure 2 VisMashup App, we found the highest velocities (marked by the longest streamlines) along the relatively low-density mass-transfer stream that connects the two stars.  This was as expected.  Material from the donor star (in the lower half of the rendered image in Figure 2) flows toward its stellar companion, reaching supersonic velocities before impacting the companion.  An oblique shock front &#150; whose location is delineated by kinks in the pink, blue, and orange streamlines &#150; terminates the component of motion perpendicular to the companion's surface.  Motion transverse to the shock becomes orbital motion in a thick, low-density disk that surrounds the companion star.


For all five choices of <math>\Delta\Omega</math>, the flow's behavior in the vicinity of the mass-transfer stream very closely resembles the behavior that Stephen Lubow and Frank Shu predicted more than 30 years ago.  Figure 3b shows the magnified view of this region of the flow from our simulation assuming <math>\Delta\Omega = - 0.041</math>.  We've reoriented this magnified image and numbered the streamlines to facilitate comparison with the Lubow and Shu illustration, which we've reprinted with permission here (see Figure 3a).  Rather than conducting a fully self-consistent 3D simulation &#150; which was computationally impractical at the time &#150; Lubow and Shu used a mathematical perturbation analysis to estimate what the flow should look like in the vicinity of the "L1" Lagrange point, as viewed from a frame of reference rotating with the correct instantaneous orbital frequency, <math>\Omega_\mathrm{frame}</math>.  The close resemblance between our 3D simulation results in the vicinity of the L1 Lagrange point, and the behavior that Lubow and Shu predicted provides a useful point of verification for our work.
For all five choices of <math>\Delta\Omega</math>, the flow's behavior in the vicinity of the mass-transfer stream very closely resembles the behavior that Stephen Lubow and Frank Shu predicted more than 30 years ago.  Figure 3b shows the magnified view of this region of the flow from our simulation assuming <math>\Delta\Omega = - 0.041</math>.  We've reoriented this magnified image and numbered the streamlines to facilitate comparison with the Lubow and Shu illustration, which we've reprinted with permission here (see Figure 3a).  Rather than conducting a fully self-consistent 3D simulation &#150; which was computationally impractical at the time &#150; Lubow and Shu used a mathematical perturbation analysis to estimate what the flow should look like in the vicinity of the "L1" Lagrange point, as viewed from a frame of reference rotating with the correct instantaneous orbital frequency, <math>\Omega_\mathrm{frame}</math>.  The close resemblance between our 3D simulation results in the vicinity of the L1 Lagrange point, and the behavior that Lubow and Shu predicted provides a useful point of verification for our work.
Line 90: Line 102:
Each star's center of mass should lie near the center of the highest density region inside each star (outlined by the nearly spherical, red isodensity surfaces in Figure 2).  When we've assigned <math>\Delta\Omega</math> a value that properly identifies the frequency at which the centers of mass of the two stars are orbiting one another, we should see very little residual motion near the donor star's center &#150; that is, streamlines rendered in white and green in Figure 2 should be quite short.  Furthermore, we expect that this residual motion should translate into concave streamline segments, mapping out simple circular motion around the center of the donor star.  When we've identified the correct value of <math>\Delta\Omega</math>, we also should expect the returning streamline nearest the mass-transfer stream (colored yellow) to remain inside the donor.  With these ideas in mind, we judge <math>\Delta\Omega = - 0.041</math>.
Each star's center of mass should lie near the center of the highest density region inside each star (outlined by the nearly spherical, red isodensity surfaces in Figure 2).  When we've assigned <math>\Delta\Omega</math> a value that properly identifies the frequency at which the centers of mass of the two stars are orbiting one another, we should see very little residual motion near the donor star's center &#150; that is, streamlines rendered in white and green in Figure 2 should be quite short.  Furthermore, we expect that this residual motion should translate into concave streamline segments, mapping out simple circular motion around the center of the donor star.  When we've identified the correct value of <math>\Delta\Omega</math>, we also should expect the returning streamline nearest the mass-transfer stream (colored yellow) to remain inside the donor.  With these ideas in mind, we judge <math>\Delta\Omega = - 0.041</math>.


Finally, we note that as the pink and blue streamlines curve around the companion star, they extend outside the companion's disk (as outlined by the blue isodensity surface) in the rendered images with the most negative specified values of <math>\Delta\Omega</math>.  These two streamlines appear to align most neatly with the distribution of material in the disk in Figure 2a, that is, for <math>\Delta\Omega = + 0.02</math>.  This suggests that there's a characteristic frequency associated with motion in the companion's disk that's different from the binary orbital frequency.
Finally, we note that as the pink and blue streamlines curve around the companion star, they extend outside the companion's disk (as outlined by the blue isodensity surface) in the rendered images with the most negative specified values of <math>\Delta\Omega</math>.  These two streamlines appear to align most neatly with the distribution of material in the disk for <math>\Delta\Omega = + 0.02</math>.  This suggests that there's a characteristic frequency associated with motion in the companion's disk that's different from the binary orbital frequency.


[[Image:Figure3_Tohline.jpg |border|center|600px|Figure 3.  A magnified view of multiple streamlines in the region of the flow where the mass-transfer stream originates.  (a = left panel) Reproduction of Figure 3 from the published work of Stephen Lubow and Frank Shu (used with permission).  (b = right panel) A magnified segment of the flow depicted in Figure 2, image D (<math>\Delta\Omega = - 0.041</math>) from this work; we've numbered the colored streamlines to aid in our comparison with the Lubow and Shu image.]]
[[Image:Figure3_Tohline.jpg |border|center|600px|Figure 3.  A magnified view of multiple streamlines in the region of the flow where the mass-transfer stream originates.  (a = left panel) Reproduction of Figure 3 from the published work of Stephen Lubow and Frank Shu (used with permission).  (b = right panel) A magnified segment of the flow depicted in Figure 2, image D (<math>\Delta\Omega = - 0.041</math>) from this work; we've numbered the colored streamlines to aid in our comparison with the Lubow and Shu image.]]

Latest revision as of 03:06, 10 March 2010

Most of the content of this Wiki document initially appeared in print as a Visualization Corner article in the May/June 2009 issue of Computing in Science & Engineering.


A Customized Python Module for CFD Flow Analysis within VisTrails
by Joel E. Tohline, Jinghua Ge, Wesley Even, & Erik Anderson

A relatively simple, customized Python module that plugs smoothly into an otherwise standard workflow within VisTrails facilitates a quantitative analysis of complex fluid flows in simulations of merging binary stars.

Introduction

Researchers in the open source community are steadily improving scientific visualization tools. These tools are providing a wider array of sophisticated probes for data analysis and a wider assortment of effective user-friendly interfaces. They're also making it easier for researchers in the computational science community — across many disciplines — to effectively analyze huge datasets by drawing on the human brain's acute ability to sort through complex and time-varying visual patterns. The astrophysics group at Louisiana State University (LSU), for example, routinely uses volume-rendering and ray-tracing algorithms in conjunction with animation techniques to examine the time-varying behavior of isodensity surfaces that arise in computational fluid dynamic (CFD) simulations of mass-transferring and merging binary star systems. Although such analyses generally provide only a qualitative identification and assessment of structure within a given dataset, the insight gained from visual inspection can nevertheless be extremely valuable. For example, it was through visual inspection that researchers at LSU initially spotted the nonlinear development of triangular-, square-, and pentagonal-shaped tidal resonances in recent simulations.

LSU's astrophysics group has begun to incorporate VisTrails into its arsenal of scientific visualization and data analysis tools. VisTrails primarily interested the group a few years ago because it provides a user-friendly workflow interface to the extensive VTK software library. It also automatically tracks the provenance of data analysis efforts. However, what most impresses us now is the ease with which VisTrails facilitates the insertion of home-grown analysis modules into an otherwise VTK-based workflow. Taking advantage of this additional programming versatility, we have gained a greater appreciation of the role that visualization tools can play in the quantitative assessment of results from large-scale simulations. In this article, we first describe the VTK-based workflow that we initially constructed in VisTrails to view streamlines within each binary mass-transfer simulation. We then describe the Python module, whose insertion into this workflow has permitted us to identify values of key rotational frequencies associated with such flows.

TERMINOLOGY
One well-defined characteristic of a binary star system is it orbital period, <math>P</math>. If the stars are in circular orbit around one another, a binary system will appear to be stationary when viewed from a frame that's rotating with an angular frequency <math>\Omega_\mathrm{frame} = 2\pi/P</math>. When modeling mass-transferring binary star systems, we've found it advantageous to perform each computational fluid dynamic (CFD) simulation on a cylindrical-coordinate grid that rotates with a frequency <math>\Omega_0 = 2\pi/P_0</math>, where <math>P_0</math> is the binary system's orbital period at the beginning of the simulation. As mass and angular momentum are transferred from one star to the other throughout the simulation, however, the binary system's orbital period &#150; and associated value of <math>\Omega_\mathrm{frame}</math> &#150; will vary. As explained in the main text, we used VisTrails to measure <math>\Delta\Omega = (\Omega_\mathrm{frame} - \Omega_0)</math> and, hence, the instantaneous orbital period <math>P = P_0/(1 + P_0 \Delta\Omega/2\pi)</math> at any time during a simulation.

Base Workflow

Within VisTrails, we initially selected various VTK-based modules to do the following, in sequence (see Figure 1):

  • Read simulation data. We used vtkPLOT3DReader to read in one file containing the <math>(x, y, z)</math> coordinate locations of every vertex on our 3D cylindrical coordinate mesh and a separate file containing the fluid's mass-density (scalar) and momentum-density (3D vector) at every grid vertex.
  • Outline cylindrical domain boundary. As shown, we enlisted vtkStructuredGridOutlineFilter, vtkPolyDataMapper, and vtkActor.
  • Define isodensity surfaces. We rendered two nested isodensity surfaces to outline high- (red) and low-density (blue) flow regions. The Red_contour and Blue_contour module groups each contain vtkContourFilter, vtkDataSetMapper, vtkProperty, and vtkActor.
  • Draw streamlines. Each of eight separate Draw_Streamlines module groups uses vtkStreamLine, vtkTubeFilter, vtkDataSetMapper, vtkProperty, vtkActor, vtkSphereSource, vtkPolyDataMapper, and vtkLODActor to trace an individual streamline within the flow. Streamline lengths are set by feeding a common Propagation_Time into all eight module groups.

VisTrails renders the output from the various workflow actors in a composite scene using vtkRenderer as viewed by an observer located at a position that vtkCamera specifies. Finally, the module vtkCell directs this scene to the VisTrails interactive spreadsheet.

In our initially constructed base workflow, VisTrails piped the 3D vector field representing the momentum density distribution from the vtkPLOT3DReader module directly into each of the eight Draw_Streamline module groups. This base workflow — which VisTrails assembles using generically available vtk modules — let us examine the behavior of streamlines in our binary mass-transfer simulations, but only from the frame of reference, <math>\Omega_0</math>, in which we originally performed each simulation (see Figure 2, with the parameter Omega_frame = 0.00).


VisMashup containing
Figure 1 & Figure 2
(Click on relevant tab to switch between figures.)

<vismashup mid=19 showspreadsheetonly="True" embedworkflow="True"/>

Figure 1: Layout of the VisTrails workflow that is used to generate Figure 2. We constructed the base workflow (everything shown excluding the custom-built SwitchCoord module and the Omega_frame parameter specification) from standard VTK-based modules. A PDF document containing this figure can be obtained by clicking on the "Download Workflow" button.

Figure 2: An image generated by our customized VisTrails workflow using the indicated values of the three variable parameters, Omega_frame <math>(= \Delta \Omega)</math>, rho_min, and Propagation_time. The 3D-rendered image displays eight equatorial-plane streamlines and a pair of isodensity surfaces (lower density surface colored blue; higher density surface colored red) that outline the structure of both stars as well as the connecting mass-transfer stream. The propagation time is the same for all eight streamlines; along six streamlines, VisTrails carries out the integration in both directions from the location marked by a small colored sphere. Streamlines are truncated prematurely if they enter a region in which the matter density drops below the value specified by rho_min, measured as a fraction of the maximum density. A new image will be generated by the VisTrails Wiki server (in accordance with the workflow shown in Figure 1) if the reader selects a different set of parameters and clicks the green "Update" button. Recommended parameter ranges:

0.0005 < rho_min < 0.05

0.1 < propagation_time < 3.5

Execute on my desktop:

VisTrails Install icon.jpg
Clicking on Figure 2's red "Execute on my desktop" button will download the Figure 1 workflow to the reader's laptop/desktop system for local execution. In order for this to work, VisTrails (version 1.4.2 or higher) must be installed on the reader's local system. (For help installing VisTrails, click the icon shown here on the right, or view this YouTube video.) Note that two data files totaling > 100 MBytes will also be transferred for analysis on the local system, so the entire download may take 10 or more minutes, depending on the network connection.

Customized Python Module

To make it possible for us to examine the properties of binary mass-transfer flows from reference frames that have a range of different angular frequencies of rotation, <math>\Omega_\mathrm{frame} = (\Omega_0 + \Delta\Omega)</math>, we wrote a Python-based module &#150; SwitchCoord &#150; for insertion into the base VisTrails workflow. The sidebar shows the complete Python source code from our customized module. The code segment that performs the required physics analysis is short and straightforward. In particular, the SwitchCoord module performs the following operations at each grid vertex:

  • converts the <math>(x, y)</math> Cartesian to <math>(R, \phi)</math> cylindrical coordinates;
  • divides the momentum components by density to obtain the velocity components if the density is greater than minp (otherwise, it sets the velocity components to zero);
  • shifts the azimuthal velocity component <math>v_\phi</math> to a new, rotating frame of reference by adding <math>R\times \Delta\Omega</math>;
  • converts the cylindrical velocity components to Cartesian velocity components; and
  • normalizes the velocities to the maximum velocity maxnorm found across the domain where densities are greater than minp.

We designed the output ports on SwitchCoord to provide access to the same type of structured arrays that vtkPLOT3DReader generates. But, in our customized VisTrails workflow, the 3D vector field that VisTrails pipes into each of the eight Draw_Streamline module groups represents the fluid's velocity distribution as viewed from the rotating frame of reference that the floating-point scalar, Omega_frame, specifies.

Interpretation of Results

Figure 2 displays a 3D rendering of the flow from one of our binary mass-transfer simulations as generated by our customized VisTrails workflow using the parameter values indicated beside the image. In particular, the streamlines shown in the default image were generated assuming a frame rotation frequency given by Omega_frame = <math>\Delta\Omega = -0.041.</math> Using the Figure 2 VisMashup App, images can be generated assuming four other values of the frame rotation frequency in the range <math> +0.02 \ge \Delta\Omega \ge -0.06.</math> By downloading and executing this workflow on a local laptop/desktop system (click the red "Execute on my desktop" button shown in Figure 2), the reader can zoom, pan, and interactively rotate any of these 3D-rendered scenes and explore a wider range of model parameter values.

We'd like to determine which value of <math>\Delta\Omega</math> provides the best measure of the binary star system's true orbital period. For all five choices of <math>\Delta\Omega</math> identified by the Figure 2 VisMashup App, we found the highest velocities (marked by the longest streamlines) along the relatively low-density mass-transfer stream that connects the two stars. This was as expected. Material from the donor star (in the lower half of the rendered image in Figure 2) flows toward its stellar companion, reaching supersonic velocities before impacting the companion. An oblique shock front &#150; whose location is delineated by kinks in the pink, blue, and orange streamlines &#150; terminates the component of motion perpendicular to the companion's surface. Motion transverse to the shock becomes orbital motion in a thick, low-density disk that surrounds the companion star.

For all five choices of <math>\Delta\Omega</math>, the flow's behavior in the vicinity of the mass-transfer stream very closely resembles the behavior that Stephen Lubow and Frank Shu predicted more than 30 years ago. Figure 3b shows the magnified view of this region of the flow from our simulation assuming <math>\Delta\Omega = - 0.041</math>. We've reoriented this magnified image and numbered the streamlines to facilitate comparison with the Lubow and Shu illustration, which we've reprinted with permission here (see Figure 3a). Rather than conducting a fully self-consistent 3D simulation &#150; which was computationally impractical at the time &#150; Lubow and Shu used a mathematical perturbation analysis to estimate what the flow should look like in the vicinity of the "L1" Lagrange point, as viewed from a frame of reference rotating with the correct instantaneous orbital frequency, <math>\Omega_\mathrm{frame}</math>. The close resemblance between our 3D simulation results in the vicinity of the L1 Lagrange point, and the behavior that Lubow and Shu predicted provides a useful point of verification for our work.

Each star's center of mass should lie near the center of the highest density region inside each star (outlined by the nearly spherical, red isodensity surfaces in Figure 2). When we've assigned <math>\Delta\Omega</math> a value that properly identifies the frequency at which the centers of mass of the two stars are orbiting one another, we should see very little residual motion near the donor star's center &#150; that is, streamlines rendered in white and green in Figure 2 should be quite short. Furthermore, we expect that this residual motion should translate into concave streamline segments, mapping out simple circular motion around the center of the donor star. When we've identified the correct value of <math>\Delta\Omega</math>, we also should expect the returning streamline nearest the mass-transfer stream (colored yellow) to remain inside the donor. With these ideas in mind, we judge <math>\Delta\Omega = - 0.041</math>.

Finally, we note that as the pink and blue streamlines curve around the companion star, they extend outside the companion's disk (as outlined by the blue isodensity surface) in the rendered images with the most negative specified values of <math>\Delta\Omega</math>. These two streamlines appear to align most neatly with the distribution of material in the disk for <math>\Delta\Omega = + 0.02</math>. This suggests that there's a characteristic frequency associated with motion in the companion's disk that's different from the binary orbital frequency.

Figure 3. A magnified view of multiple streamlines in the region of the flow where the mass-transfer stream originates. (a = left panel) Reproduction of Figure 3 from the published work of Stephen Lubow and Frank Shu (used with permission). (b = right panel) A magnified segment of the flow depicted in Figure 2, image D (<math>\Delta\Omega = - 0.041</math>) from this work; we've numbered the colored streamlines to aid in our comparison with the Lubow and Shu image.
Figure 3 (scroll over image for caption)

Summary

We've illustrated how, at one particular instant during a CFD simulation, we can determine the orbital period of our simulated binary star system. With this customized visualization tool in hand, we're in a position to determine how the orbital period and other characteristic frequencies vary with time throughout each simulation. More significantly, we now appreciate how we can modify otherwise standard VisTrails workflows to perform any of a variety of analysis tasks that are customized to our research project needs.

Addenda

Acknowledgments

Progress on this project has benefitted significantly from interactions with Claudio Silva, Juhan Frank, Patrick Motl, and Zach Byerly. This work has been supported, in part, by funding from the US National Science Foundation (AST-0708551, DGE-0504507), the US Department of Energy, NASA (ATP-NNX07AG84G), and IBM; mass-transfer simulations were made possible via allocations of computing time on TeraGrid resources (TG-MCA98N043) at the National Center for Supercomputer Applications (NCSA) and through the Louisiana Optical Network Initiative (LONI).

References

  1. J.E. Tohline, "Scientific Visualization: A Necessary Chore," Computing in Science & Eng., vol. 9, no. 6, 2007, pp. 76-81.
  2. M.C.R. D'Souza et al., "Numerical Simulations of the Onset and Stability of Dynamical Mass Transfer in Binaries," Astrophysical J., vol. 643, no. 1, 2006, pp. 381-401.
  3. P.M. Motl, et al., "The Stability of Double White Dwarf Binaries Undergoing Direct Impact Accretion," Astrophysical J., vol. 670, no. 1, 2007, pp. 1314-1325.
  4. L. Bavoil et al., "Vistrails: Enabling Interactive Multiple-View Visualizations," 2005; www.sci.utah.edu/~csilva/papers/vis2005b.pdf.
  5. S.H. Lubow and F.H. Shu, "Gas Dynamics of Semidetached Binaries," Astrophysical J., vol. 198, no. 1, 1975, pp.383-405.

About the Authors

  • Joel E. Tohline is a professor at Louisiana State University. His research interests include astrophysics, computational fluid dynamics, and high-performance computing. Tohline has a PhD in astronomy from the University of California, Santa Cruz. He's a fellow of the American Association for the Advancement of Science, and a member of the International Astronomical Union, the American Astronomical Society, and the American Physical Society. Contact him at tohline@lsu.edu.
  • Jinghua Ge is a visualization consultant at the Center for Computation & Technology (CCT) at Louisiana State University. Her research interests include scientific visualization, computer graphics, and distributed computing. Ge has a PhD in computer science from the University of Illinois, Chicago. Contact her at jinghuage@cct.lsu.edu.
  • Wesley Even is an NSF/IGERT fellow in the Department of Physics and Astronomy at Louisiana State University. His research focuses on the modeling of mass transfer in double-white-dwarf binary star systems. Contact him at weseven@physics.lsu.edu.
  • Erik Anderson is a research assistant and PhD candidate at the University of Utah. His research interests include scientific visualization, signal processing, computer graphics, and multimodal visualization. Anderson has a BS in computer science and a BS in electrical and computer engineering from Northeastern University. Contact him at eranders@sci.utah.edu.




Sidebar: SwithCoord Python Module

Here we present a complete listing of the python code from our customized SwitchCoord program module. At the beginning of the "Physics Analysis" segment of the code, we assign names to the data arrays that have been acquired as input from vtkPLOT3DReader: pcoords is a tuple that identifies the Cartesian-based coordinate location of each grid vertex, density is a scalar that specifies the mass density, and momentum is a tuple that specifies the values of the cylindrical-coordinate-based vector momentum at each grid vertex. We detail the remaining logic of the physics analysis in the main text.

import core.modules.module_registry
from core.modules.vistrails_module import Module, ModuleError
import vtk, math
version="0.0.0"
name="SwitchCoord"
identifier="edu.lsu.switchcoord"

class SwitchCoord(Module):
    def compute(self):
        minp = self.getInputFromPort("min_density")
        Domega = self.getInputFromPort("Domega")
        dataset=self.getInputFromPort("dataset")
        output = self.create_instance_of_type('edu.utah.sci.vistrails.vtk', 'vtkStructuredGrid')
        output.vtkInstance = vtk.vtkStructuredGrid()
        mydata=output.vtkInstance
        mydata.DeepCopy(dataset.vtkInstance)
        self.op(mydata, minp, omega)
        self.setResult("changed_dataset", output)

    ###################################
    ##
    ## Begin:  Physics Analysis
    ##
    ###################################

    def op(self, mydata, minp, omega):
        extent=mydata.GetExtent()
        pcoords = mydata.GetPoints().GetData()
        density = mydata.GetPointData().GetScalars("Density")
        momentum = mydata.GetPointData().GetVectors("Momentum")

        maxnorm = 0.0
        for i in range(0, mydata.GetNumberOfPoints()):
            [x, y, z] = pcoords.GetTuple3(i)  
            [_v1, _v2, _v3] = momentum.GetTuple3(i)
            p = density.GetValue(i)
            r = math.sqrt(x*x + y*y)         
            phi = math.atan2(y, x)
            if p < minp: 
                vx=vy=vz=0
            else:
                vr = _v1 / p
                vphi = _v2 / (p) + r * omega
                vz = _v3 / p
                vx = vr * math.cos(phi) - vphi * math.sin(phi)
                vy = vr * math.sin(phi) + vphi * math.cos(phi)

                norm = math.sqrt(vx*vx + vy*vy + vz*vz)
                if norm > maxnorm:
                    maxnorm = norm
            momentum.SetTuple3(i, vx, vy, vz)

        for i in range(0, mydata.GetNumberOfPoints()):
            [vx, vy, vz] = momentum.GetTuple3(i)
            vx = vx/maxnorm
            vy = vy/maxnorm
            vz = vz/maxnorm
            momentum.SetTuple3(i, vx, vy, vz)

    ###################################
    ##
    ## End:  Physics Analysis
    ##
    ###################################

def initialize(*args, **keywords):
    reg=core.modules.module_registry.registry
    reg.add_module(SwitchCoord)
    reg.add_input_port(SwitchCoord, "scalar_range", 
                       [core.modules.basic_modules.Float, 
                        core.modules.basic_modules.Float]) 
    reg.add_input_port(SwitchCoord, "min_density", core.modules.basic_modules.Float)
    reg.add_input_port(SwitchCoord, "omega", core.modules.basic_modules.Float)
    reg.add_input_port(SwitchCoord, "dataset", 
                       (reg.get_descriptor_by_name(
                'edu.utah.sci.vistrails.vtk', 'vtkStructuredGrid').module) )
    reg.add_output_port(SwitchCoord, "changed_dataset", 
                        (reg.get_descriptor_by_name(
                'edu.utah.sci.vistrails.vtk', 'vtkStructuredGrid').module) )

def package_dependencies():
    import core.packagemanager
    manager = core.packagemanager.get_package_manager()
    if manager.has_package('edu.utah.sci.vistrails.vtk'):
        return ['edu.utah.sci.vistrails.vtk']
    else:
        return []