README.md 13.3 KB
Newer Older
1
2
3
4
5
<!---



A nicely formatted online version of this README should be available here: https://hackmd.io/s/SJof5RTnG
6
The source is available here: https://hackmd.io/_HIHDpfEQ5-JQKSCucw2Sg?both
7
8
9
10
11
12
13



--->



14
# ![ExaStencils](Misc/logos/ExaStencilsLogo.png)
15

Richard Angersbach's avatar
Richard Angersbach committed
16
The ExaStencils code generation framework processes input in its own multi-layered domain-specific language (DSL) to emit highly optimized and massively parallel geometric multigrid solvers for (block-)structured grids.
17

Richard Angersbach's avatar
Richard Angersbach committed
18
19
20
21
22
This repository holds the current version of ExaStencils.

Project information and documentation are available via the official homepage: https://www.exastencils.fau.de/. 

The source code is accessible from GitLab (https://i10git.cs.fau.de/exastencils/release/) and GitHub (https://github.com/lssfau/ExaStencils/).
23
24

## Setup
25

Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
26
For building the generator, a JDK is required. We recommend using version 11.
27

28
### IDE Support
29

Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
30
We recommend using IntelliJ IDEA (the community edition is fine). Downloads can be found [here](https://www.jetbrains.com/idea/download/).
31
32
33

*Using an IDE is not required.* Instructions on how to do things without it can be found [here](#sbt).

34
#### Setting up the IDE for Coding
35

36
37
First, check that the Scala plugin is installed: File -> Settings -> Plugins

38
If you plan to commit code please use our code style. It is located in /Misc/IntelliJ/ExaStencils.xml and can be imported like this:
39
*  File -> Settings -> Editor -> Code Style -> Scala -> Import Scheme (click small gear) -> IntelliJ IDEA code style XML
40
*  locate /Misc/IntelliJ/ExaStencils.xml
41
42
*  ok

Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
43
If you are used to another IDE, e.g. Eclipse, setting the keymap to an according style may be helpful:
44
45
*  File -> Settings -> Keymap -> Eclipse

46
#### Compiling the Generator
47
48
49
50
51
52
53
54
55
56
57
58

* If IntelliJ is opened the first time:
  * Open
  * select path in which you checked out the git repository -> ok
  * ok
* If already in the IDE:
  * File -> New -> project from existing sources
  * select path in which you checked out the git repository -> ok
  * import project from external model -> sbt -> next
  * Finish
* if 'Add Files to Git' dialogue opens -> don't add anything (press cancel)
* check that everything works: Build -> Build Project
Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
59
* **note** in some configurations it might be necessary to add the Scala SDK under Project Structure -> Global Libraries. Otherwise no files will be compiled (build still succeeds).
60

61
#### Creating a JAR
62
63
64
65
66
67
68
69
70
71
72

Inside the IDE do the following to create a task to assemble the jar:
* Run -> Edit configurations
  * green plus (upper left corner) -> sbt Task
  * fill name  : assembly
  * fill tasks : assembly
  * Ok

The first step has to be done only once. Afterwards running the task is sufficient to assemble the jar(s).
* Run -> Run 'assembly' (if this is not available use Run -> Run... and select assembly manually)

Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
73
**alternatively**, adding artifacts in IntelliJ is possible as well and often faster:
74
75
76
77
78
79
80
81
82
83
84
85
* File -> Project Structure -> Project Settings -> Artifacts -> Click green plus sign -> Jar -> From modules with dependencies
    * Module: Compiler
    * Main Class: Main
    * ok
* Output Directory -> \$path_to_your_git\$\Compiler
* ok

The jar can then be created using 
* Build -> Build Artifacts -> Compiler.jar -> build

Artifacts can be added for the other sub-projects in a similar fashion.

86
### sbt
87
88
89
90
91
92
93
94

For users that don't want to use an IDE or want to compile on the command line, sbt is required.
*If you are using Windows we recommend using Ubuntu Shell which is part of the [Windows Subsystem for Linux (WSL)](https://docs.microsoft.com/en-us/windows/wsl/install-win10).*

The first step is installing sbt -- a guide can be found [here](https://www.scala-sbt.org/1.0/docs/Installing-sbt-on-Linux.html)

Next, open a shell and locate the folder the git repository has been checked out to.
Compilation is done via typing
95
96

    sbt compile
97
98
99

To assemble a jar the following command is available

100
101
102
    sbt assembly

### CImg support
Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
103
104
105
106
107
108

For CImg support, the corresponding CImg.h header file needs to be downloaded such that it can be used as ressource by our generator. This can be done in three different ways:
* for users using sbt on the command line: ```sbt downloadCImg```
* for IntelliJ users:
    * Run -> Run -> 0: Edit Configurations -> + -> sbtTask
    * Name: downloadCImg; Tasks: downloadCImg; Run
109
* for all users: directly download the required file from [here](https://github.com/dtschump/CImg) and place it in Compiler/res/
Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
110
Updating the file works the same way.
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
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
  
### VisIt support

In order to make use of VisIt's in-situ visualization capabilities, it is recommended to build VisIt from scratch. The sources can be downloaded from [GitHub](https://github.com/visit-dav/visit/releases/)

1. Download the VisIt build script (version 3.1.4)

```
wget https://github.com/visit-dav/visit/releases/download/v3.1.4/build_visit3_1_4
chmod +x build_visit3_1_4
```

2. Build 3rd party libraries

> The available libraries and options for building VisIt can be displayed via `./build_visit3_1_4 --help`. \
> You can print the relevant environment variables via `./build_visit3_1_4 --print-vars`. \
> At first, we only build the missing 3rd party packages. You can find one of the faster (and parallel) builds below. \
> Still, this can still take ~4 hours. \
> The building process can be completed faster via the `--makeflags -j4` option. \
> Note that VisIt is not built yet (`--no-visit` option). \
> Remember to replace `<INSTALL_DIR_PATH>` with, e.g., `/usr/local/visit`.

```
env PAR_COMPILER=mpicc ./build_visit3_1_4 --no-visit --mesagl --openssl --zlib --parallel --no-thirdparty --cmake --vtk --qt --qwt --python --silo --hdf5 --szip --llvm --prefix <INSTALL_DIR_PATH>
```

During this process, you might need to install one of the following dependencies:

```
sudo apt install mesa-common-dev
sudo apt-get install libxext-dev
sudo apt-get install libdrm-dev libxxf86vm-dev libxt-dev xutils-dev flex bison xcb libx11-xcb-dev libxcb-glx0 libxcb-glx0-dev xorg-dev libxcb-dri2-0-dev libxcb-xfixes0-dev
```

After that, the third-party cmake settings can be found in `./<hostname>.cmake`

3. Download VisIt

```
wget https://github.com/visit-dav/visit/releases/download/v3.1.4/visit3.1.4.tar.gz
tar -xzf visit3.1.4.tar.gz
```

4. Configure VisIt

```
cp <hostname>.cmake visit3.1.4/src/config-site/
cd visit3.1.4/src
../../cmake-3.9.3/bin/ccmake .
```

> then press 'c' to configure\
> check `VISIT_PARALLEL=ON`\
> press 'c' until 'g' is available\
> press 'g' to generate Makefile

5. Build and install VisIt

Finally, we can compile, package and install VisIt

```
# build
make -j 8

# package and install (needs sudo privileges)
# e.g. ARCH = linux-x86_64
make package
wget https://github.com/visit-dav/visit/releases/download/v3.1.4/visit-install3_1_4
chmod +x visit-install3_1_4
visit-install3_1_4 3.1.4 <ARCH> <INSTALL_DIR_PATH>
```

6. Set environment variables

```
export VISIT_HOME='<INSTALL_DIR_PATH>'
export PATH=$VISIT_HOME/bin:$VISIT_HOME/current/bin:$PATH
export SIMV2DIR=$VISIT_HOME/current/linux-x86_64/libsim/V2
export LD_LIBRARY_PATH=$SIMV2DIR/lib:$VISIT_HOME/current/linux-x86_64/lib/mesagl:$VISIT_HOME/current/linux-x86_64/lib:"${LD_LIBRARY_PATH}"
```

7. Run VisIt

```
# serial
visit
# parallel
visit -np <num processors>
```

For more input options, call `visit --help` or `visit -fullhelp`


More details for building or installing VisIt can be found here:
* https://trac.version.fz-juelich.de/vis/wiki/VisIt/build_x86
* https://www.visitusers.org/index.php?title=Build_visit_overview
* http://www.visitusers.org/index.php?title=ParallelPorting#Compiling_VisIt_to_run_in_parallel
Sebastian Kuckuk's avatar
Sebastian Kuckuk committed
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
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
### Parallel I/O Libraries

Currently, following libraries for parallel I/O are supported in ExaStencils:
* MPI I/O
* HDF-5
* PNetCDF (+ ExodusII)
* SionLib

MPI I/O is part of MPI-2 standard and is already installed on most HPC systems. However, the other I/O libraries need to be installed first. Installation guides for each dependency are listed below.

### HDF5
To build and install HDF5 version 1.12.0, the following lines can be used:
```
wget https://support.hdfgroup.org/ftp/HDF5/releases/hdf5-1.12/hdf5-1.12.0/src/hdf5-1.12.0.tar.gz
tar xvf hdf5-1.12.0.tar.gz
cd hdf5-1.12.0
CC=/path/to/bin/mpicc ./configure --enable-parallel --prefix=$HOME/hdf5

make
make install
```
Other versions can be downloaded [here](https://portal.hdfgroup.org/display/support/Downloads) and further installation guidelines can be found [here](https://support.hdfgroup.org/ftp/HDF5/current18/src/unpacked/release_docs/).

### PnetCDF

To build and install PnetCDF version 1.12.1, the following lines can be used:
```
wget http://cucis.ece.northwestern.edu/projects/PnetCDF/Release/pnetcdf-1.12.1.tar.gz
tar xvf pnetcdf-1.12.1.tar.gz
cd pnetcdf-1.12.1
CC=/path/to/bin/mpicc ./configure --prefix=$HOME/PnetCDF # setting MPICC or using --with-mpi option didnt work

make -j 8
make install
```
Other versions can be downloaded [here](http://cucis.ece.northwestern.edu/projects/PnetCDF/download.html) and further installation guidelines can be found [here](https://svn.mcs.anl.gov/repos/parallel-netcdf/trunk/INSTALL).

### ExodusII

To build and install the current version of the ExodusII library, the following lines can be used:
```
git clone https://github.com/gsjaardema/seacas.git
cd seacas && export ACCESS=`pwd`

MPI=ON ./install-tpl.sh
cd $ACCESS
mkdir build
cd build

INSTALL_PATH=$HOME/seacas FORTRAN=OFF ../cmake-exodus
make && make install

# in case of error: installing following dependencies might help
sudo apt-get install libtool m4 automake
sudo apt-get install libopenmpi-dev
```
Further installation guides and older versions can be found [here](https://github.com/gsjaardema/seacas).

### SIONlib

To build and install SIONlib version 1.7.6, following lines can be used:
```
curl "http://apps.fz-juelich.de/jsc/sionlib/download.php?version=1.7.6" -o sionlib.tar.gz
tar xvf sionlib.tar.gz
cd sionlib
274
./configure --prefix=$HOME/sionlib --disable-fortran --mpi=openmpi
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
cd build-linux-gomp-openmpi

make
make install
```
Other versions can be downloaded [here](https://www.fz-juelich.de/ias/jsc/EN/Expertise/Support/Software/SIONlib/sionlib-download_node.html;jsessionid=8FC564790A3592233CB1ECA4D4F981FF) and further installation guidelines can be found [here](https://apps.fz-juelich.de/jsc/sionlib/docu/1.7.6/installation_page.html).

### Environment

For the generated Makefiles, following environment variables need to be defined depending on the utilized I/O libraries: `HDF5_HOME`, `PNETCDF_HOME`, `SION_HOME` and `EXODUS_HOME`
```
# define home directories for new dependencies
BASEDIR=$HOME
HDF5_HOME=$BASEDIR/hdf5 ; export HDF5_HOME
PNETCDF_HOME=$BASEDIR/PnetCDF ; export PNETCDF_HOME
SION_HOME=$BASEDIR/sionlib ; export SION_HOME
EXODUS_HOME=$BASEDIR/seacas; export EXODUS_HOME

# path
PATH=$HDF5_HOME/bin:$PATH ; export PATH
PATH=$PNETCDF_HOME/bin:$PATH ; export PATH
PATH=$SION_HOME/bin:$PATH ; export PATH
PATH=$EXODUS_HOME/bin:$PATH; export PATH

# ld_library_path
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$HDF5_HOME/lib:$PNETCDF_HOME/lib:$EXODUS_HOME/lib ; export LD_LIBRARY_PATH
```


304
305
306
307
308
## First Steps

### Examples

We recommend having a look at the examples located in /Examples.
309
To generate the examples, a valid Compiler.jar has to be located in /Compiler/Compiler.jar. You can create one using any of the guides above.
310
311
312
313
314

(optional) It might be necessary to adapt the platform file used in /Examples/generateExamples.sh
(optional) By default, all examples are generated. Unrequired configurations can be deactivated in /Examples/examples.sh

If Linux is used (or the Ubuntu Shell for Windows), generating, compiling and executing the examples is scripted. The following commands can simply be executed in the folder the git repository has been checked out to:
315
316
317
318
319

    cd Examples
    ./generateExamples.sh
    ./compileExamples.sh
    ./runExamples.sh
320
321
322

### Generating User Applications

323
Generating single configurations is possible by executing the generator (Compiler project). The following command line arguments have to be provided in this exact order:
324
325
326
* Settings
* Knowledge
* Platform
327
328
329

## Documentation

330
A detailed documentation is currently work in progress. You can find the most recent version of our ExaSlang4 user documentation [here](https://www.exastencils.fau.de/sphinx/documentation/user/ExaSlang4.html).
331

Richard Angersbach's avatar
Richard Angersbach committed
332
333
334
## Contributing 

We always welcome and appreciate contributions to ExaStencils.
Richard Angersbach's avatar
Richard Angersbach committed
335
Before contributing, please refer to our [contributing guidelines](https://github.com/lssfau/ExaStencils/blob/master/CONTRIBUTING.md) first.
Richard Angersbach's avatar
Richard Angersbach committed
336

337
338
## Authors

Richard Angersbach's avatar
Richard Angersbach committed
339
The main authors are Sebastian Kuckuk, Christian Schmitt and Stefan Kronawitter. We are thankful for the work of all [contributors](https://github.com/lssfau/ExaStencils/blob/master/AUTHORS.txt).
340
341
342

## License

Richard Angersbach's avatar
Richard Angersbach committed
343
The ExaStencils code generation framework is licensed under [GPLv3](https://github.com/lssfau/ExaStencils/blob/master/COPYING.txt).
344
345
346
347
348
349
350
351

## Dependencies

This project depends on the [cloning](https://github.com/kostaskougios/cloning) and [objenesis](http://objenesis.org/) libraries which are both licensed under the Apache license version 2.0. When the CImg visualization module is used, it depends on the [CImg](https://framagit.org/dtschump/CImg) header licensed under the CeCILL-C licence.

This project depends on and deploys the [isl](https://repo.or.cz/w/isl.git) library with added [scala bindings](https://xxx.de) as well as the [Chernikova](https://xxx.de) library. All of them are licensed under the MIT license.

All dependencies are managed automatically via sbt, with the exception of CImg which has to be taken care of [manually](#CImg-support).