Module: Hydrodynamics

Modules: Hydrodynamics

Overview

Hydrodynamic simulations are an important area of astrophysics. Shape is the first astrophysical tool to introduce an interactive mesh-based setup for such simulations without the need of programming or scripting by the user. Furthermore the results of the simulations can be directly incorporated in mesh-based renderings without the need of external software. From the hydrodynamics, just like any other mesh model, can be used to generate spectral information. Filtering using the Filter Module allows you to extract regions with particular properties based on the filter settings. Exporting of the hydrodynamic simulation data allows later incorporation of the data or parts of them into a completely different rendering project.

The simulations in Shape are always intrinsically 3D on a uniform cartesian grid. The numerical algorithm in Shape was selected to run relatively fast in 3D with a minimum of variables to keep memory usage as low as possible, while still allowing to simulate the basic astrophysical phenomenology such as shocks and radiative cooling above a temperature of 10^4 K, typical to photoionized nebulae.

The details of the numerical scheme used for the hydrodynamics, its limitations and example applications are described in the following research article: W. Steffen, N. Koning, et al., 2013, MNRAS, 436, 470–478

It is recommended to use numerical hydrodynamics tools in Shape or any other application only with sufficient understanding of the the possibilities and limitations of such tools. This module in Shape was made to make access to numerical hydrodynamics easier, but if you do not have insight into the potential artifacts the numerical schemes produce, especially at low spatial resolution, it is recommended to seek the assistance of someone who does.

General Workflow

The workflow involves three overall steps: First, you set up the elements of the simulation in the 3D Module. Second, the flow parameters are set up in the Hydro Module. The simulation is started and previewed here, too. Rendering and analysis is then done as usual in the Render Module vía a dummy rendering object that is set up in the 3D Module. See below for more details on how to set up a simulation in the 3D Module.

User Interface

The user interface of the Hydro Module consists of three main parts: The visual preview panels, the menu bar at the top and the parameter panel on the right. From the drop-down list at the top of the parameter panel you have access to four sub-panels: General, Flow, Boundaries and Camera.

Menu Bar

Calculate: The Calculate Button starts a hydrodynamic simulation.

Preview: The Preview Button visualizes the initial setup of the simulation in the preview windows, where you can inspect the distribution of density, speed, temperature and pressure.

Add: Add a new windows. You can add several new windows to the preview visualization area. This allows you to simultaneously supervise the evolution of different physical quantities or look at them from different viewing angles or filter conditions.

Refresh: Refresh all views to the current state of the hydro simulation.

Cascade & Tile: Select how to arrange multiple preview windows. They can also me manually arrange by clicking on the top bar and drag them around.

Preview Preview: Each of the preview windows gets a new icon on the menu bar. Change the name in the camera parameters panel on the right to suitably represent the content of the window.

Save & Load: Save or load the complete state of the hydrodynamic simulation for the current timestep. This allows you to stop the simulation at this time and restart the simulation where you left off after loading the data back with the Open button. The Open button opens the file dialog to select the previously saved file. Loading a file also allows you to use the result in a different project and render it with a different mesh based scene. After loading a data set click the Preview button on the Menu bar to see the simulation preview.

How to set up a hydrodynamic simulation in the 3D Module

Numbers that you need to start:

The physical size of the computational domain in units of meters.
Approximate densities (in particles/m^3) of background and active objects
Initial velocities in km/s (in the 3D Module), which are then converted automatically to m/s in the Hydro Module and later back to km/s in the Render Module. Filters in the 3D Module require km/s, whereas those in the Hydro Module require m/s.
The timescale on which the simulation is likely to finish in seconds (note that 1 year is approximately px10^7 sec, which easy to remember).

Setup Render Module

The first thing to do is to set the Scene Size and Resolution in the Render Module.

Scene Size: The physical size from center to edge of the whole computing domain in meters (you may have to choose the correct units in the Units Tab of the Render Module).

Resolution: The voxel resolution for the rendering. This does not need to be the same as the hydro simulation resolution with is set in the Hydro Module.

Setup 3D Module

Hydro Type:
Each mesh object in the 3D Module has to be assigned a Hydro Type in the Hydro tab on the right.

Background:

The computing domain can not have any region that is completely empty. Therefore there has to be exactly one object with the type Background. The mesh of the background object has to enclose the full domain. Best to use a cube object with the size of the domain or larger. The background distribution of physical properties such as density or temperature may or may not be uniform as needed.

Initialize:

Object that receive all their properties at the beginning of the simulation and change only passively as a consequence of the simulation receive the hydro type Initialize. These could, for instance, be clumps or rings of high density gas.

Boundary:
Objects that are updated at every timestep or have to remain the same during the simulation are of type Boundary, since they act like a boundary condition. These could be stellar winds or jet that have to inject gas in a controlled, possibly time-variable manner. Variability is controlled in the Animation Module.

Modifiers

All hydro objects need to have at least one set of modifiers that describe their physical properties. These can either be [Density, Temperature, Velocity] or [Density, Pressure, Velocity]. Density, Temperature and Pressure must not be zero at any position in the domain otherwise the simulation will proceed only for a limited time or crash immediately. The Velocity may of course be zero.

Other modifiers may be added as usual to control the shape, orientation and animation of the objects. Any of the modifiers may be animation including those for the physical properties.

To some extent Boundary objects can be interactively moved around with the cursor or by changing numerical parameters while the simulation is running.

Set up Hydro Module

General Tab

Grid Size: The number of cells in each direction of the cubic simulation domain. It is the same in all three dimensions. Note that the computational time and memory required for a simulation strongly depend on the Grid Size. While memory increases with the power of three, the required time increases as the fourth power of this grid size, not third power. This is so, because for smaller cells in the same physical domain the time step is also smaller. Therefore to reach the same final time, more time steps are necessary. So, ramp up this number from below, say starting at 64 and monitor memory and computing time as you increase the resolution. The numbers may be any number, no need to be multiples of 2.

End time step: The number of time steps to be executed before the simulation is automatically stopped, unless the End Time is reach first.

End time: The physical time in seconds after which the simulation shall be stopped automatically, unless the End Time Step is reach first.

Resume: If a simulation as stopped or has been loaded from file, enable the Resume flag to continue the simulation. Click the Calculate Button on the Menu Bar to start resuming the computation.

Animate: If Boundary Type objects in the 3D module vary in time in their properties, geometry or position/orientation via the Animation Module, then the Animate flag must be on for this time variability to take effect.

Pause: Set this flag to temporarily pause the simulation. This can be useful to save the current state to file or generate a rendering of it in the Render Module. To continue the simulation remove the flag.

Filters: For visualization purposes various filters can be selected from the drop-down list that select certain regions according to their physical properties. The filters themselves are set in the Filters Module. Note that SI units are used, including m/s for speed (in the 3D and Render Module the speed it in km/s, so different filters are required for the same filter range). You may combine more than one filter.

Flow Tab

Courant #: The Courant number is a number that controls the stability of the solution of the numerical differential equations of fluid dynamics. This so called CFL condition expresses that the distance that any information travels during the timestep length within the mesh must be lower than the distance between mesh elements. In other words, information from a given cell or mesh element must propagate only to its immediate neighbors. The number should be less than 1, recommended to be less than 0.5, depending on the particular conditions, incl. the strength of the cooling. Note that making the Courant # smaller, also decreases the time step and hence increases the total computing time.

Gamma: The adiabatic index of the gas in the equation of state. For monoatomic gas the value is 5/3 (1.66).

Eta: The numerical viscosity coefficient. This exchanges some fraction of the conserved physical quantities between neighboring cells and helps to maintain stability. The cost for the stability is diffusion, i.e. for instance high-density regions expand into low-density ones without the need of a pressure gradient. So, the value should be as small as possible, e.g. 1e-4 or smaller. High contrast regions are particularly affected.

T0: The minimum temperature in Kelvin to be maintained if cooling becomes too strong within a timestep and would reduce the temperature below zero. For photoionized regions this value may be set to values of order 1e4 K. Otherwise to a reasonable lower value that represents physically plausible low values.

Cooling: Enable or disable explicit cooling. See the paper by Steffen et al., (2013) for details.

Cooling factor: Apply this factor to the explicit cooling calculation.

Boundaries Tab

For each side of the cubic domain the boundary condition may be set to Outflow or Reflection. If your simulation is symmetric with respect to a certain plain, then this plane could be one of the boundaries and then a setting of Reflection can be used. Most other applications will have an Outflow condition everywhere.

The difference between the two conditions is only how the velocity components of the second to last cell is copied to the last cell. For the Outflow condition the component perpendicular to the boundary is copied as it is, whereas in the Reflection it is inverted.

Camera Tab

Controls the camera viewpoint and physical variable to be visualized in each preview window. Click on the preview window for which the parameters shall be shown and set.

Name: Set the name of the preview window. It is convenient to set it similar to the physical variable to be displayed or some other name that somehow identifies the content.

Variable: Select the physical variable to be visualized in the preview window. Note: When you move the cursor over the preview window a value for the physical quantity at the cursor position is shown in the top-left corner of the preview window. This is the integrated value along the line of sight. To see the local value use the Render Slice functionality (see below) to extract a single slice. Then the value shown represents the local value of the variable.

Enable: Enable or disable this camera.

Ortho: Enable or disable orthographic projection for this camera.

Image: Edit the image display parameters for this camera.

X Y Z pos: Set the camera position. The X Y positions are currently not functional. When the Ortho mode is disabled, the Z position in terms of the size of the domain (=1) changes the distance of the camera.

X Y Z rot: Set the rotation angles of the camera per axis in degrees. The X & Y rotation can also be changed interactively by dragging the mouse over the preview window with the left button pressed. If the resolution of the simulation is small enough for your system, the preview responds interactively at a reasonable framerate. The interactive preview is rendered on the CPU and is therefore efficient only for relatively small resolutions.

Render Slice

In the Camera Tab you can scroll down to find the Render Slice controls. They allow you to display slices of the full simulation domain to closely inspect particular regions. The slices go along the coordinate axes. The initial position in terms of cell number are set with the sliders labeled X0, Y0, Z0, while the width of the slices are dX, dY, dZ. If you click on the slider handle a number field hopes that allows you to numerically set the value.

It is convenient to set the Z width of the slices to 1 and the position to the middle. Then by enabling and disabling the Render Slice with the Enable flag, one can quickly change to a visualization that allows one to read off particular values in the preview window. As mentioned above the local value is only displayed in the preview window, if the width of the slice is set to 1. Otherwise the value shown for the cursor position is the integrated value along the line of sight, where each cell counts with a distance step of 1. For instance, if the integrated value along z is 200 and the domain resolution is 100, then the average local value is 2 along the line of sight at the position of the cursor.

Output

In the Camera Tab you can scroll down to find the Output section. When enabled it will output the full state of the simulation every dSteps timesteps. Choose a location on the filesystem afer opening the Directory selection dialog by clicking on the folder button. Make sure it is a location with sufficient disk space to accommodate the amount of data that will be saved.

Status

At the bottom of the Parameters Panel on the right there are three values updated at every timestep of a simulation. They help to judge the current status and rate of progress of the simulation. It show the current total Time in seconds, the current timestep dTime and the number of Steps computed so far. Considering the ratio between the total time and the timestep is very large, then the simulation will be progressing very slowly. This could be a hint to regionally problematic physical values.