Writing a DAT-File

Biohydrodynamics Toolbox    

Writing a DAT-File

What is a DAT-File?

A DAT-File is a text file in which is described all of the experiment's features. Here is a very simple example (two_eggs.dat) of what a DAT-File looks like :

max time = 10 time step = 0.1 fish =  {     initial position = [0;0;pi/3]     initial velocity = [0.5;0;-0.5]     link = { label = egg1              mfilename = bht_ellipse              settings = [0,0,2,1,1]                         }   } fish =  {     initial position = [3;3;pi/4]     initial velocity = [-0.6;0.5;0]     link = {  label = egg2               mfilename = bht_ellipse               settings = [0,0,1.5,0.8,1]                         }   }

This file contains data for the simulation of two ellipse-shaped solids in a fluid. In this example, the articulated bodies whose features are described within the fields fish = {...} are reduced to single solids since both of them are composed of one link only). Articulated bodies' links have labels chosen by the user. The only link of the first 'fish' is labeled ' egg1' and the one of the second fish 'egg2'. The boundaries of both of them are described by the same M-File bht_ellipse.m but with distinct settings (semimajor axis, semiminor axis...). For each 'fish' is given the initial position of its center of mass, its orientation (see  Articulated Body's degrees of freedom)  and its initial velocity. The DAT-File need next to be compiled with the function bht_data_compile.m. 

Syntax 

The compiler bht_data_compile.m reads the data of the DAT-File as a large string and seeks out key words. Anything which is not a key word will be considered as comments. White-space characters and new lines are not taken into account either. 

A DAT-File is a list of fields (kew words followed by = ). Fields are optional ; when they are missing, the compiler uses default values and a warning message is displayed in the workspace.

Comprehensive list of fields 

Fields	Expected value	Status	Description
fluid density =	real positive number	optional (defaut value: 1)	The density of the fluid.
problem type =	exterior or interior	optional (default value: exterior)	Whether the fluid is confined or not (an exterior problem means that the fluid is of infinite extend). If the fluid is confined (interior problem), at least one clockwise oriented boundary has to be given.
mesh size =	real positive number	optional (default value: 0.1)	Length between two consecutive points of discretization on the boundaries.
max time =	real positive number	required	Simulation's time range goes from 0 to this value.
time step =	real positive number	required	Time between two instants at which the solution is computed.
collisions =	yes or no	optional (default value: no)	Set wheter collisions between bodies are allowed or not. If collisions are not allowed but one still occures, computations will crash. Setting this field to yes will cause computations to slow down.
epsilon =	real positive number	required when collisions = 1	Setting parameter for collisions.
alpha =	real positive number	required when collisions = 1	Setting parameter for collisions.
boundary =	fields between braces	required when problem type = interior	Introduce settings for a fixed fluid's boundary (i.e. boundary not shared with a moving solid).
fish =	fields between braces	required	Introduce settings for an articulated body.

How to describe fixed fluid's boundaries?

Fixed fluid's boundaries' settings are given within the field boundary = { ... }. Here is an example of boundary's description: 

boundary =         {mfilename =  bht_ellipse          settings = [1,3,1,2,1]          color = [0,1,1]}

As many fixed boundaries as one wishes can be added (among them and in the case of a confined fluid, only one can have clockwise orientation). The fields between braces are:

Fields	Expected value	Status	Description
mfilename =	string	required	M-File name.
settings =	array	optional (default value [])	boundary's settings.
color =	array [r g b]	optional (default value: [0 0 1])	Color the boundary will be fill with.

How to describe articulated bodies?

Solids are defined by their boundaries. BhT yields tools for boundaries' design. Once this work has been done, articulated bodies' settings are given in the DAT-File within the field fish = {...}. As many articulated bodies (they are called fishes in the DAT-File) as one wishes can be given. Here is an example of a three links articulated body description:

max time = 10 time step = 0.1 fish =  {     initial position = [0;0;0]     initial velocity = [0;0;0]     colormap = autumn      link = { label = head               mfilename = bht_ellipse               settings = [0 0 2 0.8 1]               density = 1  }      link = { label = body1               father = head               hinge coord = [2.2;0]               hinge local coord = [-2.2;0]               mfilename = bht_ellipse               settings = [0 0 2 0.6 1]               density = 1  }      link = { label = body2               father = body1               hinge coord = [2.2;0]               hinge local coord = [-2.2;0]               mfilename = bht_ellipse               settings = [0 0 2 0.4 1]               density = 1  } }

The articulated body can be visualized by using the function bht_kine_check. It looks like that at the time t=0:

The subfields of the field fish are:

Fields	Expected value	Status	Description
initial position =	column vector of three real numbers	required	The two first elemnts are the coordinates at the time t = 0 of the center of mass of the first solid composing the articulated body. The third element is the orientation of this solid.
initial velocity =	column vector of three real numbers	required	The two first elements give the velocity, at the time t = 0 of the center of mass of the first solid composing the articulated body and the third element is the initial angular velocity.
colormap =	string	optional (default value is autumn)	Set the body's links colors.
link =	fields between braces	required	Settings for a link composing the body.

Each link composing the articulated body has its own fields which are:

Fields	Expected value	Status	Description
label =	string	required	User's defined label attached to the solid.
father =	string	required excepted for the first solid composing the body.	Solid's label the current solid is attached to.
hinge coord =	column vector of two real numbers	required excepted for the first solid composing the body.	Coordinates of the hinge in the father's attached frame.
hinge local coord =	column vector of two real numbers	required excepted for the first solid composing the body.	Coordinates of the hinge in the current solid's attached frame.
mfilename =	string	required	M-File name.
settings =	array	optional (default value [])	boundary's settings.
density =	real positive number	optional (default value is fluid_density)	density of the current solid.

How to modify default values?

Default values for missing fields can easily be modified. They are set up at the beginning of the M-File bht_translation.m.

Examples of DAT-Files

DAT-File	View at the time t = 0 (as provided by bht_kine_check)
fluid_density = 1 problem type = interior mesh size = 0.05 collisions = yes alpha = 4 epsilon = 0.01 max time = 15 time step = 0.05 boundary = { mfilename = bht_round_rectangle              settings = [0 0 2 4 0.5 -1]              color = [0.9 0.9 1]} fish =  {     initial position = [0;1.3;0.1]     initial velocity = [0;0;0]     colormap = autumn      link = {  label = sinking                mfilename = bht_ellipse                settings = [0,0,1,2.5,1]                density = 1.1  }  } fish =  {     initial position = [0;-3;0.1]     initial velocity = [0;0;0]     colormap = autumn      link = {  label = floating                mfilename = bht_ellipse                settings = [0,0,1.4,0.8,1]                density = 0.9  }  }
max time = 10 time step = 0.1 boundary = { mfilename = bht_ellipse              settings = [1 2 1 1 1]              color = [1 1 0]} fish =  {     initial position = [4;0;pi/2]     initial velocity = [0;0;0]     colormap = autumn      link = { label = head               mfilename = bht_ellipse               settings = [0 0 2 0.8 1]               density = 1  }      link = { label = body1               father = head               hinge coord = [2.2;0]               hinge local coord = [-2.2;0]               mfilename = bht_ellipse               settings = [0 0 2 0.6 1]               density = 1  }      link = { label = body2               father = body1               hinge coord = [2.2;0]               hinge local coord = [-2.2;0]               mfilename = bht_ellipse               settings = [0 0 2 0.4 1]               density = 1  } }

Note: a controls M-File is required before for the use of bht_kine_check.

See also

Articulated body

Fluid's boundaries

controls M-File

bht_data_compile

bht_kine_check

BhT overview

2008 - A. Munnier and B. Pincon (Insitut Elie Cartan and INRIA Lorraine, Projet CORIDA, Nancy, France).