Installing and using Ulambator

Why and When to use Ulambator?

Ulambator solves fluid flow equations that are based on a depth averaged model (so called Brinkman equation). A prerequisite for depth-averaging is that the fluid motion takes place in a common plane and is confined between channel floor and ceiling. This confinement can be rationalized by the aspect ratio of droplet radius R divided by channel height H. When R/H >> 1 the model does an excellent job.

In fact when R/H >> 1 one could even resort to the much simpler Darcy equation. However in practical cases the confinement is often only slightly bigger than R/H ~ 1 and the lateral walls are not much farther than W/R ~ 1, where W is the channel width. These weakly confined cases require generally the solution of the 3D Stokes (or even Navier-Stokes equation). This can be very cumbersome and may only be achieved at considerable computational costs. As a desperate try one could consider to solve the 2D Stokes equation instead, whose physical interpretation would be unconfined droplet tubes.

The 2D Brinkman reconciles the 2D Stokes equation and the Darcy equation and establishes thus a model that is still dangerous for R/H = 1 but gives results with appreciable agreement to experimental observations. When the channels become confined R/H>1 a 3D simulation may become prohibitively expensive due to thin films between the droplet and channel walls, where the 2D Brinkman model may provide results in a couple of minutes on a simple Desktop PC.

The manual, tutorial and examples will be updated and corrected regularly. So if you are interested in microfluidic flow, expecially two-phase flows, and don’t have a yet satisfying mean of computation then try to use Ulambator.

If you have a question or encounter a problem don’t hesitate to write me: [email protected]

Installation

The Ulambator solver needs a C++ compiler with OpenMP support and the mathematical libraries LAPACK. The solver runs under Linux, OS X and Windows. Visualization requires Matlab (or a clone or Python) and ParaView.

All the software needed to run the code and view the results is free of charge. Nevertheless Ulambator requires a user with a little bit of programming experience.

There is a chance that compilation works right away. If not follow the instructions below.
The latest version of Ulambator can be obtained from git:
git clone git://git.code.sf.net/p/ulambator/code ulambator-code (type in your command line).

Or manually from http://sourceforge.net/p/ulambator/code/ci/master/tree.

First configure the “Makefile” by specifying your compiler, your math libraries and paths for libraries and include. Then type “make” to compile the source code. If it does not compile solve it with the indications below. If that does not help you write me an email or check the blog or discussion on http://sourceforge.net/projects/ulambator.

1) If you have no compiler installed (like g++  or icc) try one of these solutions:

Alternatively install the Intel compilers and MKL libraries for your system, https://software.intel.com/en-us/c-compilers and https://software.intel.com/en-us/intel-mkl.

2) If the compiler has been installed correctly you call the command “make comp_test” in the ulambator folder that contains the Makefile. This builds a Ulambator version without OpenMP and LAPACK and should generally work. Maybe differences from one compiler to another could pose little problems.

3) If the compiler test runs without errors, comment the “-(f)openmp” to test first the Lapack, MKL or Accelerate compilation. If there are no errors compile again with “-(f)openmp”. OpenMP is not essential but it accelerates nicely the computation on multicore systems.

If include and libraries can not be found despite the fact that they have been installed one may simply try for instance ‘locate omp.h’ or ‘locate libgomp.a’ to locate the missing files and include their directories -I/path/to/include -L/path/to/library.

4) For editing, developing and debugging we strongly advise to use an integrated development environment IDE. Windows users who installed Visual Studio already have one. The following page provides information how to setup Ulambator under Xcode and Eclipse.

Dimensionalization

Before the simulation can be run the solver has to be configured with the non-dimensional parameters of a problem. Once the results are obtained they might have to be dimensionalized in order to give relevant velocities or pressures.

We turn first to non-dimensional geometric parameters:

The length scale for one unit in the simulation can be freely chosen. The aspect ratio L/H has to be set accordingly. If a channel has a width of 100µm and a height of 20mm and one decides to represent the channel width in the simulation by 2 units, then L =50µm and L/H=2.5.

The velocity scale is determined by the material parameters surface tension γ and bulk fluid viscosity µ, therefore U = γ/μ. E.g. an inflow velocity of 7 mm/s in a channel filled with water and gas bubbles (γ = 70mPam, µ=1mPas => 70m/s) the non-dimensional inflow velocity is  0.0001.

The viscosity is non-dimensionalized by the ratio of droplet viscosity over outer fluid viscosity, λ = μ_d/ μ.

The pressure is non-dimensionalized by the surface tension divided by the length scale, P = γ/L. Or the viscosity P=µ U/L.

The time is non dimensionalized by T =L/U.

During the tutorials the (non-)dimensionalization will be made clear with examples.

Computation

In order to setup Ulambator for a specific case you need to adapt the userfolder/main_user1.cpp file or create a new main file and edit the Makefile to compile your version. Ulambator provides some high-level functions that should allow to solve a wide range of problems with only a few lines of code.

More complex configuration or manipulation is possible by changing or adding functions to the matrixblock.cpp and bndblock.cpp class. Their role and an overview of their functions is found in the still incomplete manual at the bottom of this section. The manual will be completed with time and accompanied by an online version.

 The structure of the main class is as follows:

1. Define the geometry.
2. Define the material parameters, time step and possibly remeshing of the interface.
3. Perform the calculation with a time integration and output of data.

Once the desired case is configured one compiles the program with make and runs the executable ‘ulambator_something.o.

Ulambator runs in an IDE or in the command line. Call the respective program for instance: ‘./ulambator_user1’ or ‘./ulambator_user1 1 5 0.95’ with user defined configuration and see the program running. When running on a remote system consider to add ‘./ulambator_ellipse > some_log_file.txt &’, which allows you to log-off and keep the code running.

I believe that the basic functionalities can be understood if one follows the given examples. More examples will be given soon, including the cases that we published. The tutorials can be accessed through the right navigation bar.

A word of advice: Unfortunatly there are up to now only few asserts and return messages if something does not work out. It is imperative to configure Ulambator in an IDE in order to use a debug procedure to got step by step through the code to see where the inconsistency is.

Visualization

The output data can be divided into three groups:

1. Interface geometry of the outer boundary and the droplet(s). The files contain for each time step list with x- and y-position and curvature at each point. An example for plotting the data in Matlab is provided below.
2. Logged data, a list with output at every iteration. This contains typically the time step the droplets position etc. You can plot this with you preferred program.
3. Velocity and pressure map. This data can be visualized with ParaView, which allows to render movies from simulation data. Field data and Geometry are stored in separate files but can be animated in the same view.

The ulambator repository contains a few plotting tools in the tools folder.

A few examples are displayed along with the tutorials.

 

Download

We suggest to use the git archiv for regular updates under ulambator.sourceforge.net.

For your ease the manual and the source code is provided here as well:

• manual_ulam++.pdf
• ulambator_021215.zip
• sourcecode_appendix.pdf
• ReferenceCard.pdf