Tutorial #3: My first fish

Biohydrodynamics Toolbox    

Tutorial #3: My first fish

The time has come to build our first articulated body. It will be a simple articulated fish, made up of 4 ellipse-shaped solids connected together by 3 hinges as in the following figure:

The major changes compared to the previous examples are:

• Any field link (but the head) in the DAT-File, describing a solid composing the fish, must contain a subfield father giving the label of the solid it is connected to. It must contain as well the subfields hinge coord and hinge local coord that describe how the solid is connected to its father. 
• The controls M-File is getting important: the template generated during the compilation of the DAT-File should be completed by giving the joints' angles as functions of time (together with their first and second derivatives). 

1- The DAT-File

Our fish will try to swim toward the left, starting with all of its 4 links aligned. Note that the field initial position in the DAT-File corresponds to the gravity center's coordinates of the fish's head (more generally we shall called head the only link without a field father). Before going further we recall that the origins of the frames attached to the solids must coincide with the solids' gravity centers. However, this constraint is not mandatory when you are designing your own boundaries and you are writing the related boundary M-Files. Indeed, BhT will automatically compute the gravity centers' coordinates and then shifts the origins of the local frames during the compilation (see the figure below). This process must be taken into account  when you describe the fish's architechture.

The location of any solid (but the head) is done within the field link in the following way:

• The subfield hinge coord gives the hinge's coordinates in the father's frame.
• The subfield hinge local coord gives the hinge's coordinates in the solid's local frame.

Consider the following example: we want to connect two solids denoted respectively 'father' and 'son'. We place the hinge at [1;1] in the father's frame, and at [-1;-1/3] in the local (son's) frame (the circle stands for the hinge):

Translate next the pictures to make the hinge of the right hand side coincide with the hinge of the left hand side. One gets roughly the configuration pictured to the left side of the figure below:

Note that the zero angle corresponds to the alignment of both gravity centers together with the hinge as pictured in the right of the figure.

Note also that several links could share the same father. In our case the description of the fish's hinges is easy since we start with aligned solids and the DAT-File (refered as firstfish.dat) is simple: 

max time = 90 time step = 0.1 mesh size = 0.2 fish = {     initial position = [0;0;0]     initial velocity = [0;0;0]     link = {         label = head         mfilename = bht_ellipse         settings = [0,0,2,0.5,1]      }     link = {         label = second         father = head         mfilename = bht_ellipse         settings = [0,0,2,0.5,1]         hinge coord = [3;0]         hinge local coord = [-3;0]      }     link = {         label = third         father = second         mfilename = bht_ellipse         settings = [0,0,2,0.5,1]         hinge coord = [3;0]         hinge local coord = [-3;0]      }     link = {         label = fourth         father = third         mfilename = bht_ellipse         settings = [0,0,2,0.5,1]         hinge coord = [3;0]         hinge local coord = [-3;0]      } }

The first compilation takes the form:

>> bht_data_compile('DataFilename','firstfish','ControlsFilename','firstfish_control');

so that the template for the controls M-File is created.

2-  The controls M-File 

The generated template for the controls M-File (firstfish_control.m) is as follows:  

function [c,dc,dttc] = firstfish_control(t,cont_parameters) % ====================================================== % preallocating output variables c = zeros(3,1); dc = zeros(3,1); dttc = zeros(3,1); % ====================================================== % Warning: non zero controls' velocities (dc) at the % time t = 0 may produce fish's strong drift. % ====================================================== % % % ====================================================== %                     fish 1 % ====================================================== %              hinge              control number % ______________________________________________________ %          head-second                1 %        second-third                 2 %         third-fourth                3 % ====================================================== c(1) = dc(1) = dttc(1) = % ====================================================== c(2) = dc(2) = dttc(2) = % ====================================================== c(3) = dc(3) = dttc(3) = % ====================================================== % Use the fonction BHT_CONTROLS_CHECK to check the formula

 We try an intuitive control of the form:

• theta1(t) = c1(t) = angle_max*sin(t)
• theta2(t) = c2(t) = angle_max*sin(t-tau1)
• theta3(t) = c3(t) = angle_max*sin(t-tau2)  

but in order to smooth the starting procedure these basic controls are weighted by a smooth regular function which grows smoothly from 0 to 1 during a time delay and then remains constant, equal to 1. Such a function is provided within BhT. Here is our completion of the M-File firstfish_control:

tau = 3;   % delay for smooth function % computing delay func together with 1st and 2d derivatives [f,df,d2f] = bht_simple_delay(t,tau); tau = 2; tau2 = 3; angle_max = pi/6; % precomputing some quantities st = sin(t); ct = cos(t); stmt = sin(t-tau); ctmt = cos(t-tau); stmt2 = sin(t-tau2); ctmt2 = cos(t-tau2); % ====================================================== c(1) = angle_max*st*f; dc(1) = angle_max*(ct*f + st*df); dttc(1) = angle_max*(2*ct*df + st*(d2f-f)); % ====================================================== c(2) = angle_max*stmt*f; dc(2) = angle_max*(ctmt*f + stmt*df); dttc(2) = angle_max*(2*ctmt*df + stmt*(d2f-f)); % ====================================================== c(3) = angle_max*stmt2*f; dc(3) = angle_max*(ctmt2*f + stmt2*df); dttc(3) = angle_max*(2*ctmt2*df + stmt2*(d2f-f));

3- Various checks...

First we can verify the geometry and the controls using:

>> bht_kine_check('DataFilename','firstfish','ControlsFilename','firstfish_control')

and successive clicks and on the Time + button applies the control at successive instants (without the fluid's answer however). Moreover the derivatives of the controls can be compare to numerical approximations:

>> bht_controls_check('firstfish_control',[0,5],1e-4);

See the details in the bht_controls_check help page.

4- The simulation

Here nothing changes with respect to the previous example:

>> bht_traject_compute('DataFilename','firstfish','ControlsFilename','firstfish_control');

>> bht_simulation('DataFilename','firstfish','Axis',[-30 30 -5 5],'DisplayTime','on');

We have added the option DisplayTime. Anothers interesting options are CenteredonFish and DrawCenterOfMass (see the bht_simulation help page).

5- Redoing the simulation with other parameters

Assume that you want to modify one or several parameters in the DAT-File, for instance the ellipses' semiminor axis, and to keep the controls unchanged: take care to not add the ControlsFilename option in the compilation call because your file will be overwritten. In fact, when a controls M-file with the same name already exists, a query message is displayed in the MATALB console to be sure you want to overwrite the file.

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