README.md 14.4 KB
Newer Older
1
A HPC finite element library developed for the implementation of the models of M3DISIM Inria team.
2

3
4
<!-- toc -->

5
6
7
8
9
10
11
- [Installation](#installation)
  * [Requirements](#requirements)
    + [Compilers](#compilers)
      - [Installing compilers on macOS](#installing-compilers-on-macos)
      - [Installing compilers on Ubuntu](#installing-compilers-on-ubuntu)
      - [Installing compilers on Fedora](#installing-compilers-on-fedora)
    + [Third-party libraries](#third-party-libraries)
12
    + [FYI: Embedded libraries](#fyi-embedded-libraries)
13
14
15
16
17
18
19
20
  * [MoReFEM compilation](#morefem-compilation)
    + [XCode](#xcode)
    + [CMake](#cmake)
  * [Testing MoReFEM](#testing-morefem)
- [Using MoReFEM](#using-morefem)
  * [Levels of users](#levels-of-users)
  * [Structure of the source code](#structure-of-the-source-code)
- [How to contribute](#how-to-contribute)
21
- [Continuous integration](#continuous-integration)
22
23
24
25
26
27
28
- [Documentation](#documentation)
  * [Doxygen](#doxygen)
  * [Introduction talks](#introduction-talks)
  * [Lexicon](#lexicon)
  * [Coding standards](#coding-standards)
- [Getting help](#getting-help)

29
<!-- tocstop -->
30
31
32
33
34

# Installation

## Requirements

35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
### Compilers

MoReFEM relies on modern C++ and required features shipped with new standard C++ 17. Its has been successfully tested with gcc 7.1, AppleClang 8.0 and LLVM Clang 7.0. gfortran is required by third party libraries (below).

I will detail a bit further below for three OS, but I should stress a fairly recent OS is required to be able to install a recent clang or gcc compiler!

#### Installing compilers on macOS

- Apple clang is shipped with XCode; just install XCode from the AppleStore and open it; additional components will be installed at this moment (including development tools such as git command line).
- gfortran may be taken from [this website](hpc.sourceforge.net/), you may either pick gcc-7.1-bin.tar.gz (the most recent version at the time of this writing) to install all GNU compilers or just gfortran-7.1-bin.tar.gz to install just gfortran.

Assuming it was in your Download file, than run:

````
cd /
sudo tar xzf ~/Download/gfortran-7.1-bin.tar.gz
````

and then check it is the correctly found by typing in a terminal:

````
which gfortran
````

which should return the proper version number (7.1 here).


#### Installing compilers on Ubuntu

Ubuntu distribution is rather conservative in its compiler version and your Ubuntu is probably shipped with a gcc 5.

To install a more recent one, type:

````
sudo apt-get install --no-install-recommends -y software-properties-common 
GILLES Sebastien's avatar
GILLES Sebastien committed
70
71
sudo add-apt-repository ppa:ubuntu-toolchain-r/test && sudo apt-get update \
     && sudo apt-get install -y gcc-7 g++-7 gfortran-7     
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-7 100 --slave /usr/bin/g++ g++ /usr/bin/g++-7 --slave /usr/bin/gfortran gfortran /usr/bin/gfortran-7

````

and check with

````
which g++
````

the correct version is returned.

Running again 

````
sudo update-alternatives --config gcc
````

allows you to switch back to another version of gcc if need be.


#### Installing compilers on Fedora

Contrary to Ubuntu, Fedora is shipped with fairly recent versions of compilers; check it but on recent Fedora gcc is already a recent one.


98
### Third-party libraries
99
100
101
102

MoReFEM relies on several third party libraries:

- An optimized Blas library. On macos you may use the Accelerate framework; Openblas has also been successfully tested.
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
- Lua 5.1, which is required by Ops library (more on that one below).
- Boost C++ library; Boost is present only while waiting for full support of filesystem module in libstdc++ and libc++ STL.
- Openmpi 3.0.
- Parmetis 4.0.3 used to partition the meshes.
- SuperLU\_dist 5.2.2, ScaLAPACK v2.0.2 and Mumps 5.1.2: Solvers interfaced in Petsc.
- Petsc 3.8.3: The linear algebra library in charge of the large matrices and vectors. Most of the mpi heavy-lifting is in fact handled by this library.


The [ThirdPartyCompilationFactory](https://gitlab.inria.fr/MoReFEM/ThirdPartyCompilationFactory) project on gitlab provides smooth ways to install these dependencies: either by running directly a Python script or by using one of the given Docker images.

### FYI: Embedded libraries

Four libraries are embedded in MoReFEM directly (and their compilation is already handled through MoReFEM different builds systems):

- [TClap](http://tclap.sourceforge.net), a header-only library to handle command line arguments.
- [Seldon](seldon.sourceforge.net), a linear algebra C++ library used to hande small matrices and vectors in MoReFEM. We foresee to benchmark this library against [Xtensor](https://github.com/QuantStack/xtensor) and [Eigen](eigen.tuxfamily.org).
- [Ops](https://gitlab.com/libops), a C++ library for reading configuration files.
- [Libmesh](http://pages.saclay.inria.fr/loic.marechal/libMeshb.html), a mesh utility.




## MoReFEM compilation


There are currently three different ways to compile MoReFEM library: XCode (for macOS users), SCons (soon-to-be deprecated) and CMake (introduced in early 2018).

### XCode

XCode is widely used among developers in M3DISIM team, so a XCode project is provided with MoReFEM library.

For it to work directly without having to tinker with it, the local hierarchy of projects should be:

- `/Users/${USER}/Codes/MoReFEM/CoreLibrary` which should include the repository of the main library,
- `/Users/${USER}/Codes/MoReFEM/Models` which should include the repositories of the models not embedded within the main library, typically found on [this gitlab folder](https://gitlab.inria.fr/MoReFEM/Models).

where `USER` is your login on your computer.

The commands to create this structure are:

````
cd 
mkdir -p Codes/MoReFEM/Models
cd Codes/MoReFEM
git clone https://gitlab.inria.fr/MoReFEM/CoreLibrary/MoReFEM.git CoreLibrary
````

and if you want to install one Model (say AcousticWave for the example):

````
cd ~/Codes/MoReFEM/Models
git clone https://gitlab.inria.fr/MoReFEM/Models/AcousticWave 
````

One you're there, you may run one of the embedded model left there for play here; to change the input file used you just have to edit a scheme in Product > Scheme.


### CMake


To compile the code:

GILLES Sebastien's avatar
GILLES Sebastien committed
165
- Go in cmake/PreCache directory and copy one of the file there to tailor your need (it is very similar to what is done in the SCons build). There are more choices here though: main MoReFEM libraries might for instance be compiled as one huge library (easier to link with) or as several thematic libraries (useful for dev purposes, to check the inner dependencies between them are correctly handled).
166
- Then go to the place into which you want to build your code (say a build directory at the root of MoReFEM library) and run the command (here for a single static MoReFEM library built for macOS with AppleClang compiler):
167
168

````
169
cmake -G Ninja -C ../cmake/PreCache/macos_clang_static.cmake -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=/opt ..
170
171
172
173
174
175
176
177
178
179
````

This will configure the project; to compile and install it just run:

````
ninja install
````

Make build works fine as well; however the IDE build do not seem to work satisfactorily at the moment (at least XCode version which is very slow to open).

180
181
182
183
184
You may try the code with one of the Lua files; to do so you may have to define (unless you're on a Mac and follows the convention location used within M3DISIM team):

- MOREFEM\_ROOT, which should points to the directory in which you should find this very README.md on your disk.
- MOREFEM\_RESULT\_DIR, which shouls points to wherever you want to write your outputs.

185

186
187
188
189
190
191
192
193
194
195
196
## Testing MoReFEM

From v18.16 onward, a CTest integration has been introduced. So once your code is compiled, you should run:

````
ninja test
````

and both unit tests and sanity checks for the basic models should be run. Those tests are designed to run in a couple of minutes (with of course strong dependency of the compilation mode chosen).


197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
# Using MoReFEM


## Levels of users

We have identified 4 levels of users:

- Model user: someone that takes an already implemented Model (e.g. the ones defined in Sources/ModelInstances, or some in [dedicated Model group](https://gitlab.inria.fr/MoReFEM/Models) and provides their own Lua file to compute on their own data.
- Model developer: someone able to implement its own model, using for that purpose existent parameters and operators. All the Models defined in Sources/ModelInstances are at this level of expertise.
- Advanced model developer: Same as Model developer, but who also uses up more advanced features (that are in _Advanced_ namespace). Typically, an advanced model user might develop new operators tailored for its own purpose.
- Library developer: someone that writes code involved in low level operations of the library (typically in namespace _Internal_). 


## Structure of the source code

The hierarchy of the source code is the following:

- Utilities: a lot of handy tools that might as well be used in completely different projects (e.g. displaying content of a container, creating safely a file on a filesystem, etc...)
- ThirdParty: stuff related to third party libraries: actual sources for some of them, wrappers to provide a nice C++ interface within the code, facility to avoid getting compiler warnings from header files, etc...

Both those directories are compiled together when the compilation is set to generate MoReFEM in several libraries, as they are strongly intertwined together.

- Core: This module encompass some generic stuff that may be used at every level of MoReFEM; contrary to Utilities ones however they are already specific to the library.
- Geometry: This module encompass purely geometric objects of the code, such as the mesh, geometric elements, domains and so forth.
- FiniteElement: Large module to encompass stuff closely related to finite elements: nodes and dofs, boundary conditions, finite element spaces, unknowns and so forth...
- Parameters: This module encompass the API of so-called Parameters, which are objects for which values at quadrature points might be queried.
- Operators: This module encompass operators the API for several type of operators: variational operators, interpolators, etc...
- ParameterInstances: This module provides implementation of several parameters; it is separated from Parameters module as knowledge of stuff defined in Operators is required.
- OperatorInstances: This module provides implementation of several operators. As for ParameterInstances, it is separated from Operators module as it requires stuff from Parameters and ParameterInstances.
- FormulationSolver: module that provides the base class used to define a variational formulation.
- Model: module around the Model class, which drives the whole MoReFEM program.

The modules above form the core of MoReFEM library, which may be used to create a model of your own.

Besides them, three additional modules are provided:

- PostProcessing: a module which uses up the output data to provide a usable output. For instance default output might be used to provide input for Ensight visualisation software.
- ModelInstances: few models let here to show how the library might be used to define a Model. 
- Test: several integration tests that are run before each tag. They should soon be adapted on Inria continuous integration platform.




# How to contribute

242
As explained [earlier](#levels-of-users), most of the time you shouldn't have to contribute directly to the library and should be able to define locally in your own model what you need. However, if you have somes fixes to provide or maybe something to share (for instance an operator not implemented that might be of interest for others), feel free to submit a [merge request](https://gitlab.inria.fr/MoReFEM/CoreLibrary/MoReFEM/merge_requests/new) on our gitlab.
243
244
245
246
247

MoReFEM follows the [integration manager](https://git-scm.com/book/it/v2/Distributed-Git-Distributed-Workflows) workflow; internal developers are actually using a Redmine installed on a server of M3DISIM team.



248
# Continuous integration
249

250
251
252
253
254
255
256
MoReFEM is under [Jenkins Inria continuous integration](https://ci.inria.fr/morefem/); it is a public project, meaning  you may access it provided you created an account (more similar than an 'Internal' profile in gitlab actually).

On this project, several VMs are defined with different combinations of OS, compilers and settings; several different Jenkins items are defined that may use those VMs.

If an item begins with a user name in braces (e.g. {sgilles}), you do not need to bother at all (except if you're that user!): these items are sandbox in which a given user may check the state of his working branches against continuous integration.

The other items are all related to the branch __develop__ of the main MoReFEM repository; this branch is the one onto which new mature modifications not yet pushed onto master are put.
257
258
259

See [the dedicated README](Documentation/ContinuousIntegration/README.md) to learn more about it (user and administrator alike).

260
It's highly likely that at some point in the future we switch to gitlab-ci: Jenkins is really cumbersome to maintain and the tools to interact with the outcome are not that great (they were the reason I tried Jenkins first). Furthermore, gitlab-ci would allow to follow in the repository the state of the configuration files (for Jenkins I rely on screenshots put in the Documentation folder...)
261

262
263
264
265
266
267
268
269
270
271
272
273
274
275
# Documentation

## Doxygen

Doxygen documentation is comprehensive and up-to-date; there are actually three flavors of them. For more informations, see the README.md in Documentation/Doxygen directory.

Doxygen should run with no warnings with Doxygen version 1.8.11 (change in policy in more recent versions caused lots of them due to a lesser tolerance for one-line comments).

## Introduction talks

Two explaning talks were given in 2017 to explain the structure of the library; they are in Documentation/IntroductionTalks directory.

Both were originally make in macOS Keynote; conversions to ppt and html are also given (with the later probably more useful). 'HappyHeart' was the codename of MoReFEM until late 2017.

276
277
278
279
280

## Lexicon

The main concepts of MoReFEM given on less than 3 slides each.

281
282
## Coding standards

283
Coding standards are provided in Documentation/CodingStandards. They are mostly inspired by those of [Verdandi](verdandi.sourceforge.net).
284
285
286
287


# Getting help

GILLES Sebastien's avatar
GILLES Sebastien committed
288
The library was developed primarily by Sébastien Gilles (sebastien.gilles [AT] inria.fr), with also many contributions from Gautier Bureau, a very advanced model developer which is the author of most of the [advanced models](https://gitlab.inria.fr/MoReFEM/Models).
289
290
291
292
293
294
295
296
297
298