# Gerris Flow Solver Programming Course for Dummies

(Difference between revisions)
+
-                                                                                                         % cd src                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             +
-                                                                                                         % make tags                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          +
-
+ - + - # In emacs: + - ## open any *.c or *.h file with emacs. + - ## Position the cursor on a function or variable. + - ## do ESC . to find its definition. (or M-. using the emacs Meta key convention ) + - ## do ESC * to return to the previous location (s) . + - # In vim: + - ## to be written ... + - + - + - ==== No order in which to read the code ==== + - + - There is no good order in which to read the code (I have not found it yet). + - + - + - ==== Keep a C precedence and associativity table nearby ==== + - + - A lot of macros and functions such g_assert come from the Glib. + - Keep a bookmark to the Glib documentation: [[http://library.gnome.org/devel/glib/unstable/index.html]] + - + - + - === C basics === + - + - ==== Introduction to Structures ==== + - + - + - + - struct Point { + - char name; + - double x, y; + - }; + - + - + - An example of usage + - + - + - ﻿main() + - { + - struct Point my_point; /* declaration */ + - + - my_point.x = 0. ; + - my_point.y = 1.; + - my_point.name = ‘A’; + - } + - + - + - name, x and y are members of the structure of type “Point” called my_point. We also give it a name that can be exported (printed, passed to other functions) as a character. This example shows why it is useful to use structures to store several relevant informations or data together. + - + - ==== An example: the structure GfsNorm in Gerris ==== + - + - + - struct _GfsNorm { + - gdouble bias, first, second, infty, w; + - }; + - typedef struct _GfsNorm GfsNorm + - + - + - From ''domain.h''. + - + - + - ﻿GfsNorm gfs_domain_norm_residual (GfsDomain * domain, + - FttTraverseFlags flags, + - gint max_depth, + - gdouble dt, + - GfsVariable * res) + - { + - GfsNorm n; + - gpointer data[2]; + - + - g_return_val_if_fail (domain != NULL, n); + - g_return_val_if_fail (res != NULL, n); + - + - gfs_norm_init (&n); + - data[0] = res; + - data[1] = &n; + - gfs_domain_cell_traverse (domain, FTT_PRE_ORDER, flags, max_depth, + - (FttCellTraverseFunc) add_norm_residual, data); + - #ifdef HAVE_MPI + - domain_norm_reduce (domain, &n); + - #endif /* HAVE_MPI */ + - gfs_norm_update (&n); + - + - dt *= dt; + - n.bias *= dt; + - n.first *= dt; + - n.second *= dt; + - n.infty *= dt; + - return n; + - } + - + - + - From ''domain.c'' + - + - Notice the use of + - + - * glib basic types ''gdouble, gpointer'' + - + - * glib functions ''g_return_val_if_fail'' + - + - + - ===== Note ===== + - + - This is what the [[http://library.gnome.org/devel/glib/unstable/index.html glib documentation]] says about gpointer + - + -
typedef void* gpointer;                                                                                                                                                                                                                                                                                                                                                                                                                                                                         +
-                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              +
-                                                                                                         An untyped pointer. gpointer looks better and is easier to use than void*.                                                                                                                                                                                                                                                                                                                                                                                                                           +
-
+ - + - ==== Structures that are related to other structures ==== + - + - More complex relationships between structures create the need for ''inheritance''. + - + - Below one defines two structures which have some similarities. + - The ''Square'' is a kind of ''Quadrangle''. + - + - + - struct _Quadrangle { + - Point A, B, C, D; + - }; + - + - typedef struct _Quadrangle Quadrangle + - + - + - Notice that we use typedef: this creates an "alias" for the structure name and will + - make it able to refer to itself in its list of member names. + - + - + - ﻿/* Related structure */ + - + - struct _Square { + - Point A, B, C, D; + - }; + - + - typedef struct _Square Square + - + - + - In the following ''pseudo-code'' we use the structures, for instance we define + - a function that computes the area. + - + - + - area_Quadrangle (Quadrangle X ) + - { + - Triangle ABC; + - ABC = create_triangle(X.A,X.B,X.C); + - … + - return area_Triangle (ABC) + area_Triangle (CDA) ; + - } + - + - + - If we use squares, we may need a very similar function to compute the area of + - squares. + - + - area_Square ( Square Y ) + - { + - … + - return area_Triangle (ABC) + area_Triangle (CDA) ; + - } + - + - + - + - === Elementary classes === + - + - * We want to avoid such repetitions. + - + - * Notion of parent structure: Quadrangle is the parent of Square. + - One shall from now on use the “class” terminology. A class is a structure with some + - functions attached to it, the functions are called methods. This should become clearer in + - what follows. + - + - ==== Simple example : structures with inheritance ==== + - + - + - struct _Square { + - Quadrangle parent; + - double longueur_du_cote; + - }; + - + - typedef struct _Square Square + - + - main() + - { + - Square MySquare ; /* Déclaration of Square */ + - double area; + - + - Initialize_Square(&MySquare) ; /*Initialisation */ + - area = area_Square ( MySquare ) ; + - } + - + - + - Problem: for each class we need a new function giving the area + - area_Square, area_Quadrangle, etc… + - So we will define the function "area_square" quite simply from "area_quadrangle". + - Functions that apply to a class are called the methods of the class. + - + - In C++ the methods are listed when the class is defined. + - In the Gerris/Glib Object system the situation is somewhat different. + - A structure like the above "Square" structure is created. + - Then a separated C structure is created, the ''class structure'' + - that contains the methods and other information about the class. + - + - ---- + - + - This is the skeleton of such a class in C: + - + - + - struct _Square { + - Quadrangle parent; + - double side_length; + - }; + - + - typedef struct _Square Square + - typedef struct _SquareClass SquareClass + - + - struct _SquareClass { + - /*< private >*/ + - QuadrangleClass parent_class; + - + - /*< public >*/ + - /* add extra methods here */ + - }; + - + - + - ---- + - + - ===== The gtstemplate tool ===== + - + - * Automatic class creation: Usage of the Gts library utility function gtstemplate to create a Gts Object : + - + -
+
-                                                                                                         % gtstemplate                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        +
-                                                                                                         Usage: gtstemplate [OPTIONS] Class ParentClass                                                                                                                                                                                                                                                                                                                                                                                                                                                       +
-                                                                                                         Options:                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             +
-                                                                                                         [--no-extra-data]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    +
-                                                                                                         [--no-extra-method]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  +
-                                                                                                         % gtstemplate Square Quadrangle                                                                                                                                                                                                                                                                                                                                                                                                                                                                      +
-

## Preamble

This course material is about Gerris, a general-purpose fluid mechanics code developed by Stéphane Popinet at NIWA, Wellington, New Zealand. Gerris is a free, GPL-licensed, open source code available at http://gfs.sf.net.

The intended audience is typical first-year science or engineering graduate students with either very little experience of C or with some Fortran knowledge, but willing to work hard and learn. The student should know simple C data types, pointers and functions but not structures.

S. Zaleski has taught the course several times in Paris. In the actual course a lot of talking is done in addition to the material here. Each session is 30 minutes + 15 minutes of questions.