Hydrodynamics Interface Definition

Date Author(s) Version State
02-11-2009 AvE 0.0 TBD
11-10-2010 AvE 0.1 Initial

Introduction

In this chapter we describe the common interface for all hydrodynamics, grid based codes. For particle based, SPH codes see the gravitational dynamics specifications.

Parameters

All parameters have to be accessed with functions following the template of the get_timestep and set_timestep functions. A parameter access function may only retrieve or update the value of a single parameter. After all parameters have been set, the commit_parameters function should be called, this gives the code the opertunity prepare the model.

class amuse.community.interface.hydro.HydrodynamicsInterface
commit_parameters

Perform initialization in the code dependent on the values of the parameters. Called after the parameters have been set or updated.

int32 commit_parameters();
FUNCTION commit_parameters()
  INTEGER :: commit_parameters
END FUNCTION
Returns:
0 - OK
Code is initialized
-1 - ERROR
Error happened during initialization, this error needs to be further specified by every code implemention
-2 - ERROR
not yet implemented

Grid Management

Most hydrodynamical codes work on grids or a hierarchy of grids. The following methods define the functionality to setup and query the grids.

class amuse.community.interface.hydro.HydrodynamicsInterface
get_index_of_position

Retrieves the i,j and k index of the grid cell containing the given x, y and z position. The cell is looked up in the grid specified by index_of_grid.

int32 get_index_of_position(float64 x, float64 y, float64 z, 
  int32 index_of_grid, float64 * i, float64 * j, float64 * k);
FUNCTION get_index_of_position(x, y, z, index_of_grid, i, j, k)
  INTEGER :: index_of_grid
  DOUBLE PRECISION :: x, y, z, i, j, k
  INTEGER :: get_index_of_position
END FUNCTION
Parameters:
  • x (float64, IN) –
  • y (float64, IN) –
  • z (float64, IN) –
  • index_of_grid (int32, IN) –
  • i (float64, OUT) –
  • j (float64, OUT) –
  • k (float64, OUT) –
Returns:

get_index_range_inclusive()

Returns the min and max values of indices in each direction. The range is inclusive, the min index and max index both exist and can be queried. The total number of cells in one direction is max - min + 1.

The returntype is a list of 3 tuples, each tuples contains the minimum and maximum value in the index range.

Fo C/C++ codes the returned values will usually be: ((0, nmeshx-1), (0, nmeshy-1), (0, nmeshz-1))

Fo Fortran codes the returned values will usually be: ((1, nmeshx), (1, nmeshy), (1, nmeshz))

get_position_of_index

Retrieves the x, y and z position of the center of the cell with coordinates i, j, k in the grid specified by the index_of_grid

int32 get_position_of_index(int32 i, int32 j, int32 k, 
  int32 index_of_grid, float64 * x, float64 * y, float64 * z);
FUNCTION get_position_of_index(i, j, k, index_of_grid, x, y, z)
  INTEGER :: i, j, k, index_of_grid
  DOUBLE PRECISION :: x, y, z
  INTEGER :: get_position_of_index
END FUNCTION
Parameters:
  • i (int32, IN) –
  • j (int32, IN) –
  • k (int32, IN) –
  • index_of_grid (int32, IN) –
  • x (float64, OUT) –
  • y (float64, OUT) –
  • z (float64, OUT) –
Returns:

set_boundary(xbound1, xbound2, ybound1, ybound2, zbound1, zbound2)

Sets the boundary conditions on the grid. Boundaries can be: “reflective”, “periodic”.

Parameters:
  • xbound1 – inner or left boundary in the x direction
  • xbound2 – outer or right boundary in the x direction
  • ybound1 – inner or front boundary in the y direction
  • ybound2 – outer or back boundary in the y direction
  • zbound1 – inner or bottom boundary in the z direction
  • zbound1 – outer or top boundary in the z direction
setup_mesh(nmeshx, nmeshy, nmeshz, xlength, ylength, zlength)

Sets the number of mesh cells in each direction, and the length of the grid in each direction.

Parameters:
  • nmeshx – number of mesh cells in the x direction
  • nmeshy – number of mesh cells in the y direction
  • nmeshz – number of mesh cells in the z direction
  • xlength – total length of the grid in the x direction
  • ylength – total length of the grid in the y direction
  • zlength – total length of the grid in the z direction

Grid state

Grid points in a hydrodynamics code have a well known, minimal state. This state is is defined by a density, momentum density and energy density. The state can be retrieved and updated with the following functions.

class amuse.community.interface.hydro.HydrodynamicsInterface
get_grid_state
int32 get_grid_state(int32 i, int32 j, int32 k, int32 index_of_grid, 
  float64 * rho, float64 * rhovx, float64 * rhovy, float64 * rhovz, 
  float64 * en, int32 number_of_points);
FUNCTION get_grid_state(i, j, k, index_of_grid, rho, rhovx, rhovy, rhovz,  &
    en, number_of_points)
  INTEGER :: i, j, k, index_of_grid, number_of_points
  DOUBLE PRECISION :: rho, rhovx, rhovy, rhovz, en
  INTEGER :: get_grid_state
END FUNCTION
Parameters:
  • i (int32, IN) –
  • j (int32, IN) –
  • k (int32, IN) –
  • index_of_grid (int32, IN) –
  • rho (float64, OUT) –
  • rhovx (float64, OUT) –
  • rhovy (float64, OUT) –
  • rhovz (float64, OUT) –
  • en (float64, OUT) –
  • number_of_points (int32,) –
Returns:

set_grid_state
int32 set_grid_state(int32 i, int32 j, int32 k, float64 rho, 
  float64 rhovx, float64 rhovy, float64 rhovz, float64 en, 
  int32 index_of_grid, int32 number_of_points);
FUNCTION set_grid_state(i, j, k, rho, rhovx, rhovy, rhovz, en,  &
    index_of_grid, number_of_points)
  INTEGER :: i, j, k, index_of_grid, number_of_points
  DOUBLE PRECISION :: rho, rhovx, rhovy, rhovz, en
  INTEGER :: set_grid_state
END FUNCTION
Parameters:
  • i (int32, IN) –
  • j (int32, IN) –
  • k (int32, IN) –
  • rho (float64, IN) –
  • rhovx (float64, IN) –
  • rhovy (float64, IN) –
  • rhovz (float64, IN) –
  • en (float64, IN) –
  • index_of_grid (int32, IN) –
  • number_of_points (int32,) –
Returns:

Grid State, Extension Mechanism

Not all information of a grid point can be transfered with the fill_grid_state and get_grid_state functions. To support other properties (like pressure or MHD properties), the code can define get_ and set_ functions. These functions must get or set one scalar property (1 argument) or a vector property (3 arguments)

class amuse.community.interface.hydro.HydrodynamicsInterface
set_grid_density
int32 set_grid_density(int32 i, int32 j, int32 k, float64 rho, 
  int32 index_of_grid, int32 number_of_points);
FUNCTION set_grid_density(i, j, k, rho, index_of_grid, number_of_points)
  INTEGER :: i, j, k, index_of_grid, number_of_points
  DOUBLE PRECISION :: rho
  INTEGER :: set_grid_density
END FUNCTION
Parameters:
  • i (int32, IN) –
  • j (int32, IN) –
  • k (int32, IN) –
  • rho (float64, IN) –
  • index_of_grid (int32, IN) –
  • number_of_points (int32,) –
Returns:

set_grid_energy_density
int32 set_grid_energy_density(int32 i, int32 j, int32 k, float64 en, 
  int32 index_of_grid, int32 number_of_points);
FUNCTION set_grid_energy_density(i, j, k, en, index_of_grid,  &
    number_of_points)
  INTEGER :: i, j, k, index_of_grid, number_of_points
  DOUBLE PRECISION :: en
  INTEGER :: set_grid_energy_density
END FUNCTION
Parameters:
  • i (int32, IN) –
  • j (int32, IN) –
  • k (int32, IN) –
  • en (float64, IN) –
  • index_of_grid (int32, IN) –
  • number_of_points (int32,) –
Returns:

set_grid_momentum_density
int32 set_grid_momentum_density(int32 i, int32 j, int32 k, 
  float64 rhovx, float64 rhovy, float64 rhovz, int32 index_of_grid, 
  int32 number_of_points);
FUNCTION set_grid_momentum_density(i, j, k, rhovx, rhovy, rhovz,  &
    index_of_grid, number_of_points)
  INTEGER :: i, j, k, index_of_grid, number_of_points
  DOUBLE PRECISION :: rhovx, rhovy, rhovz
  INTEGER :: set_grid_momentum_density
END FUNCTION
Parameters:
  • i (int32, IN) –
  • j (int32, IN) –
  • k (int32, IN) –
  • rhovx (float64, IN) –
  • rhovy (float64, IN) –
  • rhovz (float64, IN) –
  • index_of_grid (int32, IN) –
  • number_of_points (int32,) –
Returns:

Model evolution

The hydrodynamics codes evolve the properties all grid cells in time. The following functions are needed to control the evolution in the code.

class amuse.community.interface.hydro.HydrodynamicsInterface
initialize_grid

Perform accounting before evolving the model. This method will be called after setting the parameters and filling the grid points but just before evolving the system

int32 initialize_grid();
FUNCTION initialize_grid()
  INTEGER :: initialize_grid
END FUNCTION
Returns:

Diagnostics

The state of the code can be queried, before, during and after the model calculations. The following function can be used to query the exact model time.

class amuse.community.interface.hydro.HydrodynamicsInterface
get_time

Returns the current model time.

int32 get_time(float64 * value);
FUNCTION get_time(value)
  DOUBLE PRECISION :: value
  INTEGER :: get_time
END FUNCTION
Parameters:value (float64, OUT) –
Returns:

External fields

Some Hydrodynamics codes support external acceleration or potential fields. The following functions can be used to enter a gravitational potential field.

class amuse.community.interface.hydro.HydrodynamicsInterface