Wiki

#MoFEM Programmer User Manual

##1 Introduction

The aim of this page is to give guidance on programming related issues in moFEM and suggest places for more information.

Go to Contents

##2 How to Contribute

The MoFEM source code is managed by the version control system git. Git is a distributed version control system allowing each user to hold a version of the source code locally (local repository) to work on which can then be added to the server for all to access (global repository). Due to the distributed nature different versions of the code exist and so changes made are required to be added to the server where the conflicts are resolved. The hosting service used for MoFEM for the global respository is Bitbucket, which is git compliant.

A more detailed description of how to use git can be found here: https://www.atlassian.com/git/tutorial

For those seeking to use a GUI then we would recommend SourceTree (it's free).

####2-1 Getting a Copy of the Code - Clone Repository

The act of copying the global reposotory from the server onto your local machine is known as cloning. At the top of this page there is a clone button which provides the required URL and git clone command. This command should be used in a directory where you wish to host the source code. Note this should be different from where you are building your code. This can also be done through a GUI, such as in SourceTree.

####2-2 Contributing to the Code - Pull Requests

To contribute changes or additions to the code back to a main branch a Pull Request is required. This is called through the Bibucket website interface. The administrator will review the proposed changes and may suggest modifications, and when complete the changes will be merged. Before submitting a pull request make sure the code has been tested and passed as instructed below.

####2-3 Code Testing

Tests have been written into MoFEm to check that certain aspects of the code are not brocken or give erroneous results. To run the tests use the following command in your build directory:

ctest -D Experimental

To check the outcome of the tests consult the CDash testing website. Particular attention should be shown to those which have failed.

##3 Numerical Examples

####3-1 Introduction

MoFEM contains numerical examples for a range of different finite element problem types, which can be found in the examples folder.

####3-2 Adding/modifying examples

To add an example to the source code the programmer is required to modify the relevant makefiles to ensure the compiled code is placed in the correct build location. There are two makefiles which require modification:

CMakeLists.txt in /examples
CMakeLists.txt in /examples/example_name, where example_name is the folder name of the example

The first one creates the relevant subdirectory in the examples build directory. For example: if you wanted to create an example folder called "elasticity" then you would modify the CMakeLists.txt to include the subdirectory elasticity in the examples build directory using:

add_subdirectory("${PROJECT_SOURCE_DIR}/examples/elasticity")

The second makefile creates the required executable files in the build directory and creates their links based on dependencies. It also copies any files which are required from the source directory into the build directory. For example, this could be the required mesh files located in /meshes. An example CmakeLists.txt is shown below with comments:

#Executable file from compiled source code which is created in build directory
add_executable(elasticity elasticity.cpp)
#Links the requried dependencies
target_link_libraries(elasticity mofem_student_body mofem_Field ${PROJECT_LIBS})

#Copies mesh files to build directory
cm_export_file("../../meshes/LShape.cub" export_files_elasticity)

#Copies other files to the build directory - this case the README
file(COPY
    ${CMAKE_CURRENT_SOURCE_DIR}/README
    DESTINATION ${CMAKE_CURRENT_BINARY_DIR}/)

#test code
add_test(SimpleElasticityTest ${MPI_RUN} -np 4 ${CMAKE_CURRENT_BINARY_DIR}/elasticity 
  -my_file LShapeCoarse.cub -ksp_type fgmres -pc_type asm -sub_pc_type lu -log_summary)

install(TARGETS elasticity DESTINATION bin)

Note the above makefile also contains a test function.

##4 Floating Point Arithmetic

####4-1 Introduction

Computation is the act of calculating an input to give an output. The data to be computed is represented in a specific language for a computer's architecture. This difference in languages and inherent limitations creates problems which if not identified can create spurious results. Therefore when employing the use of computers for scientific computing purposes it's of great importance to be aware of some of the issues and how to avoid them.

####4-2 Base 2 Representation - Binary

Computers operate on a base 2 number system i.e. 1 or 0. This is due to the digital nature of their electronics. However we normally operate on base 10 (decimal). And so the base 10 input number is converted to a base 2 equivalent as shown below:

134 in base 10:

1*10^2+3*10^1+3*10^0=134

Example binary number: 101

Converted to decimal:

1*2^2+0*2^1+2*1^0 = 5

Multiplication is denoted by *

Convert back to decimal using remainders:

5/2 = 2 r 1

2/2 = 1 r 0

2/1 = 1 r 1

Combine remainders:101

For further information on binary numbers: http://www.math.grin.edu/~rebelsky/Courses/152/97F/Readings/student-binary#1011-a

Rational numbers can be expressed as fractions. However there are times when base 10 rational numbers are converted to base 2 and the result is irrational. An example of this can be seen when converting 1/10 in base 10 to base 2: 0.00011001100110011... .The number of digits will continue to infinity with each digit increasing the approximation but never reaching it and so the number will be rounded at some point depending on the number type and machine precision. The act of rounding introduces an error into the number.

This has important implications as can be demonstrated through an exmaple. If you're adding two numbers together which have rational representations in base 10 but not in base 2 then there can be a surprising result.

C++ code:

#include <iostream>

int main()
{
  std::cout.precision(30); // show 16 digits
  double a = 0.1;
  double b = 0.2;

  std::cout <<"a = " << a << "\n";
  std::cout <<"b = " << b << "\n";
  std::cout <<"a + b  = " << a+b  << "\n";
}

Output:

a = 0.100000000000000005551115123126
b = 0.200000000000000011102230246252
a + b  = 0.300000000000000044408920985006

As can be seen from the output the decimal representations are not exact and the output is not exactly 0.3.

This example has been inspired by a python article: http://docs.python.org/2/tutorial/floatingpoint.html

####4-4 Floating Point Numbers

Floating point numbers are the most common way of storing non-integer numbers in computers. They come in particularly useful when dealing with very large or small numbers and can be considered similar to scientific notation. For example: the distance between the sun and the earth is 149600000 km. If that number were to be stored in memory the 0 place holders would be included resulting in wastage. If however a floating point form were used then the memory space could be reduced to: 1.496x10^8 km. Note that the act of shortening a number can result in loss of precision and therefore loss of information.

Go to Contents