------------------------------------------------------ The FronTier README ------------------------------------------------------ For information on the FronTier development, please visit the FronTier homepage at : http://frontier.ams.sunysb.edu INDEX 1. Introduction 2. How to get it 3. Unpacking 4. Contents 5. Configuring and Building 6. Running the test programs 7. Viewing the output 8. Selecting built-in interface initialization and velocity fields 9. Build your own initial interface 10. Build your own velocity field function --------------- 1. Introduction --------------- This library package is destined for those who wish to exploit the many features of the FronTier code. For solving problems using front tracking methods, this library provides an excellent way to design complex fronts, in one, two or three dimensions. ---------------- 2. How to get it ---------------- This distribution can be freely downloaded and distributed under the terms of the LGPL from: http://frontier.ams.sunysb.edu/download ------------ 3. Unpacking ------------ The FronTier library package is available in the .tar.gz format. Some older versions of tar might require the -o option upon extraction to ensure that new directories can be created. ----------- 4. Contents ----------- If the archive is unpacked correctly, you should have the following files and directories: The FronTier/ directory is the "root" directory of the FronTier distribution. In it should be located the src/ directory. It also contains various files required for configuration, and this README file. The src/ dir contains source code subdirectories: driver/ hyp/ tri/ front/ intfc/ pak/ util/ gas/ TSTT/ testfront/ example/ ------------ 5. Configuring and Building ------------ Configuring for the FronTier library: In the FronTier/ directory simply type "./configure", if you are unsure how to use this configuration script, or what configurations options are available, type "./configure --help" Building the FronTier with HDF package: In the FronTier/ directory simply type "./configure --whth-hdf=hdf_path. where hdf_path is the directory the HDF is installed. The inclusion of HDF package gives user capability of producing output as hdf file which can be immediately converted to .gif movies (through hdf2gif). Building the FronTier gas dynamics executable: In the FronTier/ directory simply type "./configure --with-gas", if you are unsure how to use this configuration script, or what configurations options are available, type "./configure --help" This option is not available for pure geometry package FronTier_Lite. To to build what you have configured, in the FronTier/ directory type "make". After make has finished there will be a new subdirectory in FronTier called lib/ which will contain all libraries built in the distribution which were chosen, if the gas dynamics executable was chosen, it will be in FronTier/src/gas/i686/gas. To test if FronTier has built properly type "make test". This will compile 2 test programs in FronTier/example and FronTier/testfront/. These test programs are a good place to start understanding how FronTier works, and they can be used as a template for incorporating FronTier into your own programs. Configuring with HDF FronTier uses HDF4.2r1 for 2D animation output which can be easily converted into movies in .gif format. To download this package, go to: http://hdf.ncsa.uiuc.edu/release4/obtain.html Both zlib and jpeglib are needed. Follow the instruction of INSTALL in HDF4.2r1 directory to build the library. Note, it is found that for Linux system, there is a bug in HDF4.2r1 during compiling. To fix it, after configuring, go to the mfhdf/hdiff and in Makefile, search line: LIBS = -ljpeg -lz and change it to: LIBS = -ljpeg -lz -lm After building HDF, re-configure FronTier with: ./configure --with-hdf=(hdf main directory, such as /usr/local/HDF4.2r1) [other options] and recompile the code. ------------ 6. Running the test programs ------------ After compiling the linFronTier.a, one can test the library by running testing code calling the software. Template code for application of FronTier-Lite library are stored in FronTier/example (for 2D) and FronTier/example3d (3D) directories. These contain simple and benchmark testing cases. To run them, copy one of them to example.c, for example: cp example01.c example.c make example -o output If HDF library is linked to the code, the run will produce an output file named output.hdf. Use hdf2gif output.hdf output.gif give use a animated .gif file which can be viewed by web browser, animate or display or other graphics tools. After the FronTier package has been configured and built, it can be tested. The example directory in the FronTier distribution contains a very short program which demonstrates the initialization and running of a FronTier simulation. This example includes 2 sample functions, one that initializes an interface, and one that sets up a very simple velocity function. The testfront directory contains a larger code that has the ability to initialize many different interfaces, and apply a variety of velocity fields to them. To build the code in the testfront and example directories, while in the main FronTier directory, type "make test". The FronTier build system also has a built in diagnostic/benchmark series of runs for the testfront program. The input cards for these runs are in FronTier/testfront/in directory. After the test programs have been built, the testfront diagnostic/benchmarks can be run, while in the main FronTier directory by typing "make testrun". To run a single testfront case cd into FronTier/testfront and type: ./testfront -i input-card -o output for example: testfront -i in/disk-c -o disc-c-out This will direct the output of the testfront program to a series of files with the prefix of disc-c-out. You can also use the shell "xx" in the testfront directory: xx disk-c This will take the input from in/disk-c from the in directory and put the output file disc-c in the out/ directory. ------------ 7. Viewing the output ------------ The output of a FronTier simulation is the resulting interface after being propagated due to a velocity field. The easiest way to view this is enabling vtk output by using vtk_interface_plot() function. The testfront program has a function called test_output_front() which includes vtk_interface_plot() along with a few other functions for other file formats. To view a vtk file you need to install the data viewer called paraview. Paraview can be downloaded from: http://www.paraview.org/ Paraview can be installed on linux and windows systems, and is very easy to use. ------------ 8. Selecting built-in interface initialization and velocity fields ------------ The testfront.c driver in the testfront directory uses FronTier's built-in interface initialization function and velocity field function. These functions prompt the user for information using input files. The function f_init_interface() follows the input file method to answer questions about interface initialization. For 2D, the possible interface types that can be initialized are a straight line, an ellipse, multiple circles, sine waves, and a slotted disk. For 3D, there is a plane, an ellipse, multiple ellipsoids, a hyperboloid, a paraboloid, a randomly perturbed interface, or superimposed sine waves. The input file prompting system will ask the user to supply parameters in order to change shape and size of the corresponding initial interface. The testfront program uses the init_front_velocity() function to setup a velocity function automatically. The choices of velocity fields are translation, radial motion, shear motion, sinusoidal motion, circular rotation, normal motion, bi-polar velocity, and vortex velocity. Again, the user needs to supply the parameters for these velocity field functions via the prompting system. ------------ 9. Build your own initial interface ------------ The built in functions are very simplistic and most users of FronTier will usually require something not provided by the the built in functions, when using FronTier for their research purposes. Therefore a short example program which demonstrates interface initialization and velocity functions is included in the FronTier/example directory. This section exists to help describe what is going on in the example program, through the use of code snippets. To get a full understanding of this program you may want to open another window and read the FronTier/example code at the same time. If more help is need in writing initialization functions or velocity functions feel free to contact the Stony Brook AMS FronTier group for help. This sample code lets the user define his/her own computational domain and mesh grid. The only input needed for this code is the ft_control card which allows the user to specify the appropriate front redistribution parameters. In order to initialize the interface, the user needs to supply a data structure containing the parameter of the level surface. The following code snippet shows how to initialize a circle: /******************************************************************** * Level function parameters for the initial interface * ********************************************************************/ typedef struct { /* equation for line is x^2/a^2 + y^2/b^2 = 1 */ float x0; float y0; float R; } CIRCLE_PARAMS; //This data structure is to be casted as a POINTER (void*) as //func_params in level_func_pack. The user also needs to supply //a level function for the initial interface, for example: /******************************************************************** * Sample (circle) level function for the initial interface * ********************************************************************/ static float level_circle_func( POINTER func_params, float *coords) { CIRCLE_PARAMS *circle_params = (CIRCLE_PARAMS*)func_params; float x0,y0,R,dist; x0 = circle_params->x0; y0 = circle_params->y0; R = circle_params->R; dist = sqrt(sqr(coords[0] - x0) + sqr(coords[1] - y0)) - R; return dist; } /* end level_circle_func */ //This function also needs to be assigned to the level_func_pack.func. //Then a call of f_init_interface() will initialize the interface. All of //this is also demonstrated in the FronTier/example directory. ------------ 10. Build your own velocity field function ------------ To build your own velocity field, you need to have a data structure containing the parameters for the velocity function. For example: /******************************************************************** * Velocity function parameters for the front * ********************************************************************/ typedef struct { float i1,i2; float cen1[2],cen2[2]; } DOUBLE_VORTEX_PARAMS; //and the velocity function: /******************************************************************** * Sample (circle) velocity function for the front * ********************************************************************/ static int double_vortex_vel( POINTER params, Front *front, POINT *p, HYPER_SURF_ELEMENT *hse, HYPER_SURF *hs, float *vel) { DOUBLE_VORTEX_PARAMS *dv_params = (DOUBLE_VORTEX_PARAMS*)params; float *coords = Coords(p); float d1,d2; float s1,s2; float *cen1 = dv_params->cen1; float *cen2 = dv_params->cen2; float dx1,dy1; float dx2,dy2; dx1 = coords[0] - cen1[0]; dy1 = coords[1] - cen1[1]; dx2 = coords[0] - cen2[0]; dy2 = coords[1] - cen2[1]; d1 = sqrt(sqr(dx1) + sqr(dy1)); d2 = sqrt(sqr(dx2) + sqr(dy2)); s1 = dv_params->i1/2.0/PI/d1; s2 = dv_params->i2/2.0/PI/d2; vel[0] = s1*dy1/d1 + s2*dy2/d2; vel[1] = -s1*dx1/d1 - s2*dx2/d2; } /* end double_vortex_vel */ They are assigned to velo_func_pack on the lines in the main function: velo_func_pack.func_params = (POINTER)&dv_params; velo_func_pack.func = double_vortex_vel; Then a call of init_front_velocity() will install the velocity field into the advance_front() by itself. *** Last change : 13 Sept. 2005