mirror of
https://github.com/paboyle/Grid.git
synced 2025-06-17 23:37:06 +01:00
Adding the initial documentation
This commit is contained in:
Guido Cossu
33
_pages/docs/bug_report.md
Normal file
33
_pages/docs/bug_report.md
Normal file
@ -0,0 +1,33 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Reporting a bug"
|
||||
header:
|
||||
overlay_color: "#C70039"
|
||||
permalink: /docs/bug_report/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include base_path %}
|
||||
|
||||
{% octicon alert height:32 class:"right left" aria-label:hi %} __To help us tracking and solving more efficiently issues with Grid, please report problems using the [issue system of GitHub](https://github.com/paboyle/Grid/issues) rather than sending emails to Grid developers.__
|
||||
|
||||
We also suggest to have a brief look at the [closed issues pages](https://github.com/paboyle/Grid/issues?q=is%3Aissue+is%3Aclosed) and check whether the problem has been addressed already.
|
||||
|
||||
{% capture notice-text %}
|
||||
1. Check that the code is pointing to the `HEAD` of `develop` or any commit in `master` which is tagged with a version number.
|
||||
2. Give a description of the target platform (CPU, network, compiler).
|
||||
3. Give the exact `configure` command used.
|
||||
4. Attach `config.log`.
|
||||
5. Attach `config.summary`.
|
||||
6. Attach the output of `make V=1`.
|
||||
7. Describe the issue and any previous attempt to solve it. If relevant, show how to reproduce the issue using a minimal working example.
|
||||
{% endcapture %}
|
||||
|
||||
<div class="notice--warning">
|
||||
<h4>When you file an issue, please go though the following checklist:</h4>
|
||||
{{ notice-text | markdownify }}
|
||||
</div>
|
||||
|
||||
{% include paginator.html %}
|
||||
25
_pages/docs/comm_interfaces.md
Normal file
25
_pages/docs/comm_interfaces.md
Normal file
@ -0,0 +1,25 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Supported communication interfaces"
|
||||
header:
|
||||
overlay_color: "#5DADE2"
|
||||
permalink: /docs/comm_interfaces/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include base_path %}
|
||||
|
||||
The following options can be use with the `--enable-comms=` option to target different communication interfaces:
|
||||
|
||||
| `<comm>` | Description |
|
||||
| ------------- | -------------------------------------------- |
|
||||
| `none` | no communications |
|
||||
| `mpi[-auto]` | MPI communications |
|
||||
| `mpi3[-auto]` | MPI communications using [MPI-3 shared memory](https://software.intel.com/sites/default/files/managed/eb/54/An_Introduction_to_MPI-3.pdf) |
|
||||
| `shmem ` | Cray SHMEM communications |
|
||||
|
||||
For `mpi` and `mpi3` the optional `-auto` suffix instructs the `configure` scripts to determine all the necessary compilation and linking flags. This is done by extracting the informations from the MPI wrapper specified in the environment variable `MPICXX` (if not specified `configure` will scan though a list of default names).
|
||||
|
||||
{% include paginator.html %}
|
||||
49
_pages/docs/knl_build.md
Normal file
49
_pages/docs/knl_build.md
Normal file
@ -0,0 +1,49 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Building on a Intel Knights Landing"
|
||||
header:
|
||||
overlay_color: "#5DADE2"
|
||||
permalink: /docs/knl_build/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include base_path %}
|
||||
The information included in this page has been updated on *November 2016* and it is valid for the release version 0.6.0.
|
||||
|
||||
|
||||
The following configuration is recommended for the [Intel Knights Landing](http://ark.intel.com/products/codename/48999/Knights-Landing) platform:
|
||||
|
||||
``` text
|
||||
../configure --enable-precision=double\
|
||||
--enable-simd=KNL \
|
||||
--enable-comms=mpi3-auto \
|
||||
--with-gmp=<path> \
|
||||
--with-mpfr=<path> \
|
||||
--enable-mkl \
|
||||
CXX=icpc MPICXX=mpiicpc
|
||||
```
|
||||
|
||||
where `<path>` is the UNIX prefix where GMP and MPFR are installed. If you are working on a Cray machine that does not use the `mpiicpc` wrapper, please use:
|
||||
|
||||
``` text
|
||||
../configure --enable-precision=double\
|
||||
--enable-simd=KNL \
|
||||
--enable-comms=mpi3 \
|
||||
--with-gmp=<path> \
|
||||
--with-mpfr=<path> \
|
||||
--enable-mkl \
|
||||
CXX=CC CC=cc
|
||||
```
|
||||
|
||||
|
||||
#### Notes
|
||||
- [GMP](https://gmplib.org/) is the GNU Multiple Precision Library.
|
||||
- [MPFR](http://www.mpfr.org/) is a C library for multiple-precision floating-point computations with correct rounding.
|
||||
- Both libaries are necessary for the RHMC support.
|
||||
|
||||
|
||||
|
||||
|
||||
{% include paginator.html %}
|
||||
86
_pages/docs/quick-start-guide.md
Normal file
86
_pages/docs/quick-start-guide.md
Normal file
@ -0,0 +1,86 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Quick start guide"
|
||||
header:
|
||||
overlay_color: "#5DADE2"
|
||||
permalink: /docs/quick-start-guide/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include toc icon="gears" title="Quick-start" %}
|
||||
|
||||
Please send all pull requests to the `develop` branch.
|
||||
{: .notice--warning}
|
||||
|
||||
## Quick start
|
||||
First, start by cloning the repository:
|
||||
|
||||
``` bash
|
||||
git clone https://github.com/paboyle/Grid.git
|
||||
```
|
||||
|
||||
Then enter the cloned directory and set up the build system:
|
||||
|
||||
``` bash
|
||||
cd Grid
|
||||
./bootstrap.sh
|
||||
```
|
||||
|
||||
Now you can execute the `configure` script to generate makefiles as in this example (here from a build directory):
|
||||
|
||||
``` bash
|
||||
mkdir build
|
||||
cd build
|
||||
../configure --enable-precision=double --enable-simd=AVX --enable-comms=mpi-auto --prefix=<path>
|
||||
```
|
||||
|
||||
where `--enable-precision=` sets the default precision,
|
||||
`--enable-simd=` sets the SIMD type, `--enable-
|
||||
comms=`, and `<path>` should be replaced by the prefix path where you want to
|
||||
install Grid (optional). Other options are detailed in the next section, you can also use `configure
|
||||
--help` to display them. Like with any other program using GNU autotool, the
|
||||
`CXX`, `CXXFLAGS`, `LDFLAGS`, ... environment variables can be modified to
|
||||
customise the build.
|
||||
|
||||
Finally, you can build and install Grid:
|
||||
|
||||
``` bash
|
||||
make
|
||||
make install #this is optional
|
||||
```
|
||||
|
||||
To minimise the build time, only the tests at the root of the `tests` directory are built by default. If you want to build tests in the sub-directory `<subdir>` you can execute:
|
||||
|
||||
``` bash
|
||||
make -C tests/<subdir> tests
|
||||
```
|
||||
|
||||
## Build configuration options
|
||||
|
||||
A full list of configurations options is available with the `./configure --help` command:
|
||||
|
||||
Here we report the more common ones.
|
||||
|
||||
- `--prefix=<path>`: installation prefix for Grid.
|
||||
- `--with-gmp=<path>`: look for GMP in the UNIX prefix `<path>`
|
||||
- `--with-mpfr=<path>`: look for MPFR in the UNIX prefix `<path>`
|
||||
- `--with-fftw=<path>`: look for FFTW in the UNIX prefix `<path>`
|
||||
- `--enable-lapack[=<path>]`: enable LAPACK support in Lanczos eigensolver. A UNIX prefix containing the library can be specified (optional).
|
||||
- `--enable-mkl[=<path>]`: use Intel MKL for FFT (and LAPACK if enabled) routines. A UNIX prefix containing the library can be specified (optional).
|
||||
- `--enable-numa`: enable [numa first touch policy](http://queue.acm.org/detail.cfm?id=2513149) optimization (default `no`)
|
||||
- `--enable-simd=<code>`: setup Grid for the SIMD target `<code>` (default: `GEN`). [List of possible SIMD targets](/Grid/docs/simd_targets/).
|
||||
- `--enable-precision={single|double}`: set the default precision (default: `double`).
|
||||
- `--enable-precision=<comm>`: Use `<comm>` for message passing (default: `none`). [List of possible comm targets](/Grid/docs/comm_interfaces/).
|
||||
- `--enable-rng={ranlux48|mt19937}`: choose the RNG (default: `ranlux48 `).
|
||||
- `--disable-timers`: disable system dependent high-resolution timers.
|
||||
- `--enable-chroma`: enable Chroma regression tests. A compiled version of Chroma is assumed to be present.
|
||||
|
||||
|
||||
More details on the *Getting started* menu entries on the left.
|
||||
|
||||
|
||||
This document was updated on November 2016.
|
||||
{: .notice}
|
||||
|
||||
65
_pages/docs/running_knl.md
Normal file
65
_pages/docs/running_knl.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Running on a Intel Knights Landing"
|
||||
header:
|
||||
overlay_color: "#5DADE2"
|
||||
permalink: /docs/running_knl/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include base_path %}
|
||||
{% include toc icon="gears" title="Contents" %}
|
||||
|
||||
These are few suggestions in order to get the best performance on the Intel Knights Landing (KNL).
|
||||
|
||||
### Bind the memory allocation to the MCDRAM NUMA node
|
||||
|
||||
The KNL has two memory systems, the DDR4 (~90 GFlops/s) and the High Bandwidth Memory (MCDRAM, ~400 Gflops/s).
|
||||
Each of the two memory system is attached to a different [NUMA context](https://software.intel.com/en-us/articles/optimizing-applications-for-numa).
|
||||
|
||||
On a KNL node the command `numactl --hardware` will report which NUMA context is connected to the faster MCDRAM.
|
||||
A typical report looks like this
|
||||
|
||||
``` text
|
||||
node 0 size: 98178 MB
|
||||
node 0 free: 92899 MB
|
||||
node 1 cpus:
|
||||
node 1 size: 16384 MB
|
||||
node 1 free: 15926 MB
|
||||
```
|
||||
|
||||
In this case the node 1 is related to the 16GB MCDRAM (this is the typical situation on KNLs)
|
||||
|
||||
To bind the memory allocation to NUMA node 1 use
|
||||
|
||||
``` bash
|
||||
numactl --membind 1 ./your-executable
|
||||
```
|
||||
|
||||
### Controlling threading
|
||||
|
||||
The number of threads can be set in GRID at runtime by the flag
|
||||
|
||||
``` text
|
||||
--threads <#threads>
|
||||
```
|
||||
|
||||
A finer control can be achieved using the environment variable `KMP_HW_SUBSETS` (or the deprecated `KMP_PLACE_THREADS`).
|
||||
|
||||
From the [Intel developer guide](https://software.intel.com/en-us/node/684313):
|
||||
|
||||
>The KMP_HW_SUBSETS variable controls the hardware resource that will be used by the program. This variable specifies the number of sockets to use, how many cores to use per socket and how many threads to assign per core. For example, on Intel® Xeon Phi™ coprocessors, while each coprocessor can take up to four threads, specifying fewer than four threads per core may result in a better performance. While specifying two threads per core often yields better performance than one thread per core, specifying three or four threads per core may or may not improve the performance. This variable enables you to conveniently measure the performance of up to four threads per core.
|
||||
|
||||
A typical setting for the best performance on a single node is to use **62 cores with 1 threads per code**, on the bash shell this is set by
|
||||
|
||||
``` bash
|
||||
export KMP_HW_SUBSETS=62c,1t
|
||||
```
|
||||
|
||||
The information included in this page has been updated on *November 2016* and it is valid for the release version 0.6.0.
|
||||
{: .notice}
|
||||
|
||||
|
||||
{% include paginator.html %}
|
||||
41
_pages/docs/simd_targets.md
Normal file
41
_pages/docs/simd_targets.md
Normal file
@ -0,0 +1,41 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Supported SIMD architectures"
|
||||
header:
|
||||
overlay_color: "#5DADE2"
|
||||
permalink: /docs/simd_targets/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include base_path %}
|
||||
|
||||
The following options can be used for `--enable-simd=` flag to target different SIMD instruction sets:
|
||||
|
||||
| `<code>` | Description |
|
||||
| ----------- | -------------------------------------- |
|
||||
| `GEN` | generic portable vector code |
|
||||
| `SSE4` | SSE 4.2 (128 bit) |
|
||||
| `AVX` | AVX (256 bit) |
|
||||
| `AVXFMA` | AVX (256 bit) + FMA |
|
||||
| `AVXFMA4` | AVX (256 bit) + FMA4 |
|
||||
| `AVX2` | AVX 2 (256 bit) |
|
||||
| `AVX512` | AVX 512 bit |
|
||||
| `QPX` | QPX (256 bit) |
|
||||
|
||||
Alternatively, some CPU codenames can be directly used:
|
||||
|
||||
| `<code>` | Description |
|
||||
| ----------- | -------------------------------------- |
|
||||
| `KNC` | [Intel Xeon Phi codename Knights Corner](http://ark.intel.com/products/codename/57721/Knights-Corner) |
|
||||
| `KNL` | [Intel Xeon Phi codename Knights Landing](http://ark.intel.com/products/codename/48999/Knights-Landing) |
|
||||
| `BGQ` | Blue Gene/Q |
|
||||
|
||||
#### Notes (November 2016):
|
||||
- We are currently supporting AVX512 only for the Intel compiler. GCC and clang will appear in future versions, if the compilers provide sufficient support.
|
||||
- For BG/Q only [bgclang](http://trac.alcf.anl.gov/projects/llvm-bgq) is supported. We do not presently plan to support more compilers for this platform.
|
||||
- BG/Q performances are currently rather poor. This is being investigated for future versions.
|
||||
|
||||
|
||||
{% include paginator.html %}
|
||||
24
_pages/docs/travis.md
Normal file
24
_pages/docs/travis.md
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
layout: single
|
||||
title : "Documentation"
|
||||
author_profile: false
|
||||
excerpt: "Travis Continous Integration framework"
|
||||
header:
|
||||
overlay_color: "#5DADE2"
|
||||
permalink: /docs/travis/
|
||||
sidebar:
|
||||
nav : docs
|
||||
---
|
||||
{% include base_path %}
|
||||
<!-- {% include toc icon="gears" title="Helpers" %} -->
|
||||
|
||||
For continous testing of every commit we use the [Travis CI framework](https://travis-ci.org/).
|
||||
|
||||
The current status is
|
||||
|
||||
| Branch | Status |
|
||||
|---------- | ------ |
|
||||
| [Master](https://travis-ci.org/paboyle/Grid) | [](https://travis-ci.org/paboyle/Grid) |
|
||||
| [Develop](https://travis-ci.org/paboyle/Grid) | [](https://travis-ci.org/paboyle/Grid) |
|
||||
|
||||
{% include paginator.html %}
|
||||
Reference in New Issue
Block a user