Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update FAQ.md #2195

Merged
merged 3 commits into from
Oct 11, 2023
Merged

Update FAQ.md #2195

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9875557
Update FAQ.md
FabioLuporini Sep 6, 2023
a577484
Update FAQ.md
FabioLuporini Oct 11, 2023
99b9bce
Merge branch 'master' into update-faq-1
FabioLuporini Oct 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 36 additions & 27 deletions FAQ.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@
- [Does Devito optimize complex expressions](#does-devito-optimize-complex-expressions)
- [How are abstractions used in the seismic examples](#how-are-abstractions-used-in-the-seismic-examples)
- [What environment variables control how Devito works](#what-environment-variables-control-how-devito-works)
- [What are the accepted combinations of PLATFORM, ARCH, and LANGUAGE](#what-are-the-accepted-combinations-of-platform-arch-and-language)
- [How do you run the unit tests from the command line](#how-do-you-run-the-unit-tests-from-the-command-line)
- [What is the difference between f() and f[] notation](#what-is-the-difference-between-f-and-f-notation)
- [What is the indexed notation](#what-is-the-indexed-notation)
Expand Down Expand Up @@ -226,7 +227,8 @@ You will note that this method uses placeholders for the material parameter arra
## What environment variables control how Devito works

### How to get the list of Devito environment variables
You can get the list of environment variables with the following python code:

You can get the list of environment variables and all their possible values with the following python code:

```python
from devito import print_defaults
Expand All @@ -244,26 +246,6 @@ These environment variables can either be set from the shell or programmatically
| programmatically | configuration['language'] = 'openmp' |


### Table of values for Devito environment variables
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

removed as obsolete and unmaintanable

replaced suggesting the user to execute print_defaults instead ( a few lines above)


Note the default values are in **bold**. Links in the table take you to a section describing how the variables controls the behavior of Devito execution.

| Variable | Values |
|:---|:---|
| [DEVITO_ARCH](#DEVITO_ARCH) | **custom**, gnu, gcc, clang, pgcc, pgi, nvc, cuda, osx, intel, icpc, icc, intel-knl, knl, gcc-4.9, gcc-5, gcc-6, gcc-7, gcc-8, gcc-9, gcc-10, gcc-11, gcc-12 |
| [DEVITO_PLATFORM](#DEVITO_PLATFORM) | **cpu64**, cpu64-dummy, intel64, snb, ivb, hsw, bdw, skx, klx, clx, knl, knl7210, arm, power8, power9, nvidiaX] |
| [DEVITO_PROFILING](#DEVITO_PROFILING) | **basic**, advanced, advisor |
| [DEVITO_BACKEND](#DEVITO_BACKEND) | **core**, void |
| [DEVITO_DEVELOP](#DEVITO_DEVELOP) | **True**, False |
| [DEVITO_OPT](#DEVITO_OPT) | noop, **advanced**, advanced-fsg, (noop, C), (noop, openmp), (noop, openacc), (advanced, C), (advanced, openmp), (advanced, openacc), (advanced-fsg, C), (advanced-fsg, openmp), (advanced-fsg, openacc)] |
| [DEVITO_MPI](#DEVITO_MPI) | **0**, 1, basic, diag, overlap, overlap2, full |
| [DEVITO_LANGUAGE](#DEVITO_LANGUAGE) | 0, 1, **C**, openmp, openacc (0==C, 1==openmp)|
| [DEVITO_AUTOTUNING](#DEVITO_AUTOTUNING) | **off**, basic, aggressive, max, [off, preemptive], [off, destructive], [off, runtime], [basic, preemptive], [basic, destructive], [basic, runtime], [aggressive, preemptive], [aggressive, destructive], [aggressive, runtime], [max, preemptive], [max, destructive], [max, runtime] |
| [DEVITO_LOGGING](#DEVITO_LOGGING) | DEBUG, PERF, **INFO**, WARNING, ERROR, CRITICAL |
| [DEVITO_FIRST_TOUCH](#DEVITO_FIRST_TOUCH) | **0**, 1 |
| [DEVITO_JIT_BACKDOOR](#DEVITO_JIT_BACKDOOR) | **0**, 1 |
| [DEVITO_IGNORE_UNKNOWN_PARAMS](#DEVITO_IGNORE_UNKNOWN_PARAMS) | **0**, 1 |

### Description of Devito environment variables

#### DEVITO_ARCH
Expand All @@ -272,12 +254,12 @@ Used to select a specific "backend compiler". The backend compiler takes as inpu
#### DEVITO_PLATFORM
This environment variable is mostly needed when running on GPUs, to ask Devito to generate code for a particular device (see for example this [tutorial](https://github.com/devitocodes/devito/blob/master/examples/gpu/01_diffusion_with_openmp_offloading.ipynb)). Can be also used to specify CPU architectures such as Intel's -- Haswell, Broadwell, SKL and KNL -- ARM, AMD, and Power. Often one can ignore this variable because Devito typically does a decent job at auto-detecting the underlying platform.

#### DEVITO_LANGUAGE
Specify the generated code language. The default is `C`, which means sequential C. Use `openmp` to emit C+OpenMP or `openacc` for C+OpenACC.

#### DEVITO_PROFILING
Choose the performance profiling level. This is also automatically increased with `DEVITO_LOGGING=PERF` or `DEVITO_LOGGING=DEBUG`, in which case this environment variable can be ignored.

#### DEVITO_BACKEND
The execution backend. Since Devito v4.2, this environment variable can be ignored.

#### DEVITO_DEVELOP
Mostly useful for developers when chasing [segfaults](https://github.com/devitocodes/devito/blob/24ede9131473f69c1e44ba3b852f8654d3fd953e/devito/data/allocators.py#L373).

Expand All @@ -287,9 +269,6 @@ Choose the performance optimization level. By default set to the maximum level,
#### DEVITO_MPI
Controls MPI in Devito. Use `1` to enable MPI. The most powerful MPI mode is called "full", and is activated setting `DEVITO_MPI=full`. The "full" mode implements a number of optimizations including computation/communication overlap.

#### DEVITO_LANGUAGE
Specify the generated code language. The default is `C`, which means sequential C. Use `openmp` to emit C+OpenMP or `openacc` for C+OpenACC.

#### DEVITO_AUTOTUNING
Search across a set of block shapes to maximize the effectiveness of loop tiling (aka cache blocking). You can choose between `off` (default), `basic`, `aggressive`, `max`. A more aggressive autotuning should eventually result in better runtime performance, though the search phase will take longer.

Expand All @@ -309,6 +288,36 @@ Set `DEVITO_IGNORE_UNKNOWN_PARAMS=1` to avoid Devito raising an exception if one
[top](#Frequently-Asked-Questions)


## What are the accepted combinations of PLATFORM, ARCH, and LANGUAGE

#### LANGUAGE={C,openmp}

These two languages can be used with virtually any PLATFORM and ARCH.

With a device PLATFORM (e.g., `nvidiaX`, `amdgpuX`, or `intelgpuX`), the compiler will generate OpenMP code for device offloading.

When using OpenMP offloading, it is recommended to stick to the corresponding vendor compiler, so `ARCH=amdclang` for AMD, `ARCH={icc,icx,intel}` for Intel, and `ARCH=nvc` for NVidia.

#### LANGUAGE=openacc

Requires: `PLATFORM=nvidiaX` and `ARCH=nvc`.

The legacy PGI compiler is also supported via `ARCH=pgcc`.

#### LANGUAGE=cuda

_DevitoPRO only._

Requires: `PLATFORM=nvidiaX` and `ARCH=cuda`.

#### LANGUAGE=hip

_DevitoPRO only._

Requires: `PLATFORM=amdgpuX` and `ARCH=hip`.

[top](#Frequently-Asked-Questions)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since this is here, you should drop line 303

https://github.com/devitocodes/devito/pull/2195/files#diff-c7bd425fd98aad1f9fef20099637bcbdcfadeb566ba1f83bb40ce484f195b8cfR303

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know what line 303 pointed to


## How do you run the unit tests from the command line
In addition to the [tutorials]( https://www.devitoproject.org/devito/tutorials.html), the unit tests provide an excellent way to see how the Devito API works with small self-contained examples. You can exercise individual unit tests with the following python code:

Expand Down
Loading