Skip to content

Commit ffa5d82

Browse files
author
jkinsky
authored
Update ISO3DFD readme - unguided version (#1048)
Restructured to match new template. Rewrote some sections for clarity. Updated headings and fixed formatting issues.
1 parent 1636a37 commit ffa5d82

File tree

1 file changed

+115
-90
lines changed
  • DirectProgramming/DPC++/StructuredGrids/iso3dfd_dpcpp

1 file changed

+115
-90
lines changed

‎DirectProgramming/DPC++/StructuredGrids/iso3dfd_dpcpp/README.md‎

Lines changed: 115 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,161 @@
11
# `ISO3DFD` Sample
2+
ISO3DFD refers to three-dimensional finite-difference wave propagation in isotropic media. The `ISO3DFD` sample is a three-dimensional stencil to simulate a wave propagating in a 3D isotropic medium. The sample code shows common challenges when targeting SYCL* devices (GPU/CPU) in complex applications.
23

3-
The ISO3DFD sample refers to Three-Dimensional Finite-Difference Wave Propagation in Isotropic Media. It is a three-dimensional stencil to simulate a wave propagating in a 3D isotropic medium. It shows some of the more common challenges when targeting SYCL* devices (GPU/CPU) in more complex applications.
4-
5-
For comprehensive information in using oneAPI programming, see the [Intel® oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programming-guide), and use search or the table of contents to find relevant information.
6-
7-
8-
| Property | Description
9-
|:--- |:---
10-
| What you will learn | How to offload the computation to GPU using Intel® oneAPI DPC++/C++ Compiler
11-
| Time to complete | 15 minutes
4+
| Area | Description
5+
|:--- |:---
6+
| What you will learn | How to offload complex computations to a GPU
7+
| Time to complete | 15 minutes
128

139
## Purpose
14-
ISO3DFD is a finite difference stencil kernel for solving the 3D acoustic isotropic wave equation, which can be used as a proxy for propagating a seismic wave. In this sample, kernels are implemented as 16th order in space, with symmetric coefficients, and 2nd order in time scheme without boundary conditions. The sample can explicitly run on the GPU and/or CPU to propagate a seismic wave, which is a compute intensive task.
10+
The `ISO3DFD` sample is a finite difference stencil kernel for solving the 3D acoustic isotropic wave equation. The solution can be used as a proxy for propagating a seismic wave.
1511

16-
The code will first attempt to execute on an available GPU and fallback to the system's CPU if a compatible GPU is not detected. By default, the output will print the device name where SYCL*-compliant code ran along with the grid computation metrics, flops and effective throughput. For validating results, a serial version of the application will be run on CPU, and results will be compared to the SYCL*-compliant version.
12+
In this sample, kernels are implemented as 16th order in space, with symmetric coefficients, and 2nd order in time scheme without boundary conditions. The sample code can explicitly run on a GPU or CPU, or on both, to propagate a seismic wave. The calculations are compute intensive.
1713

18-
| iso3dfd sample | Performance data
19-
|:--- |:---
20-
| Scalar baseline -O2 | 1.0
21-
| SYCL* | 2x speedup
22-
23-
> **Note**: You can find more information about this sample at [Explore SYCL* with Samples from Intel](https://www.intel.com/content/www/us/en/develop/documentation/explore-dpcpp-samples-from-intel/top.html#top_STEP4_ISO3DFD).
14+
> **Note**: You can find information about this sample at [Explore SYCL* with Samples from Intel](https://www.intel.com/content/www/us/en/develop/documentation/explore-dpcpp-samples-from-intel/top.html#top_STEP4_ISO3DFD).
2415
2516
## Prerequisites
26-
| Optimized for | Description
27-
|:--- |:---
28-
| OS | Ubuntu* 18.04 <br>Windows* 10
29-
| Hardware | Skylake with GEN9 or newer
30-
| Software | Intel&reg; oneAPI DPC++/C++ Compiler
17+
| Optimized for | Description
18+
|:--- |:---
19+
| OS | Ubuntu* 18.04 <br> Windows* 10
20+
| Hardware | Skylake with GEN9 or newer
21+
| Software | Intel® oneAPI DPC++/C++ Compiler
3122

3223
## Key Implementation Details
33-
The basic SYCL* implementation explained in the code includes the use of the following :
34-
- SYCL* local buffers and accessors (declare local memory buffers and accessors to be accessed and managed by each workgroup)
24+
The basic SYCL* implementation explained in the code includes:
25+
- SYCL local buffers and accessors (declare local memory buffers and accessors to be accessed and managed by each workgroup)
3526
- Code for Shared Local Memory (SLM) optimizations
36-
- SYCL* kernels (including parallel_for function and nd-range<3> objects)
37-
- SYCL* queues (including custom device selector and exception handlers)
27+
- SYCL kernels (including parallel_for function and nd-range<3> objects)
28+
- SYCL queues (including custom device selector and exception handlers)
29+
30+
The code attempts to run on a compatible GPU first. If a compatible GPU is not found, then the program runs on the CPU.
31+
32+
For validating results, a serial version of the application will be run on CPU, and results will be compared to the SYCL version. In some cases, the code will use a field programmable array (FPGA) emulator to run the SYCL variant.
33+
34+
The program output includes the device name that ran the code along with the grid computation metrics, flops, and effective throughput.
35+
36+
| `ISO3DFD` Sample | Performance data
37+
|:--- |:---
38+
| Scalar baseline -O2 | 1.0
39+
| SYCL | 2x speedup
40+
41+
## Set Environment Variables
42+
When working with the command-line interface (CLI), you should configure the oneAPI toolkits using environment variables. Set up your CLI environment by sourcing the `setvars` script every time you open a new terminal window. This practice ensures that your compiler, libraries, and tools are ready for development.
3843

3944
## Build the `ISO3DFD` Program for CPU and GPU
4045
> **Note**: If you have not already done so, set up your CLI
41-
> environment by sourcing the `setvars` script located in
42-
> the root of your oneAPI installation.
46+
> environment by sourcing the `setvars` script in the root of your oneAPI installation.
4347
>
44-
> Linux:
48+
> Linux*:
4549
> - For system wide installations: `. /opt/intel/oneapi/setvars.sh`
46-
> - For private installations: `. ~/intel/oneapi/setvars.sh`
50+
> - For private installations: ` . ~/intel/oneapi/setvars.sh`
51+
> - For non-POSIX shells, like csh, use the following command: `bash -c 'source <install-dir>/setvars.sh ; exec csh'`
4752
>
48-
> Windows:
53+
> Windows*:
4954
> - `C:\Program Files(x86)\Intel\oneAPI\setvars.bat`
55+
> - Windows PowerShell*, use the following command: `cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'`
5056
>
51-
>For more information on environment variables, see Use the setvars Script for [Linux or macOS](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html), or [Windows](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
57+
> For more information on configuring environment variables, see [Use the setvars Script with Linux* or macOS*](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-linux-or-macos.html) or [Use the setvars Script with Windows*](https://www.intel.com/content/www/us/en/develop/documentation/oneapi-programming-guide/top/oneapi-development-environment-setup/use-the-setvars-script-with-windows.html).
5258
5359
### Include Files
54-
The include folder is located at `%ONEAPI_ROOT%\dev-utilities\latest\include` on your development system.
60+
The include folder is at `%ONEAPI_ROOT%\dev-utilities\latest\include` on your development system. You might need to use some of the resources from this location to build the sample.
5561

56-
### Use Visual Studio Code* (Optional)
62+
>**Note**: You can get the common resources from the [oneAPI-samples](https://github.com/oneapi-src/oneAPI-samples/tree/master/common) GitHub repository.
5763
58-
You can use Visual Studio Code (VS Code) extensions to set your environment, create launch configurations, and browse and download samples.
64+
### Use Visual Studio Code* (VS Code) (Optional)
65+
You can use Visual Studio Code* (VS Code) extensions to set your environment,
66+
create launch configurations, and browse and download samples.
5967

6068
The basic steps to build and run a sample using VS Code include:
61-
- Download a sample using the extension **Code Sample Browser for Intel&reg; oneAPI Toolkits**.
62-
- Configure the oneAPI environment with the extension **Environment Configurator for Intel&reg; oneAPI Toolkits**.
63-
- Open a Terminal in VS Code (**Terminal>New Terminal**).
64-
- Run the sample in the VS Code terminal using the instructions below.
69+
1. Configure the oneAPI environment with the extension **Environment Configurator for Intel® oneAPI Toolkits**.
70+
2. Download a sample using the extension **Code Sample Browser for Intel® oneAPI Toolkits**.
71+
3. Open a terminal in VS Code (**Terminal > New Terminal**).
72+
4. Run the sample in the VS Code terminal using the instructions below.
6573

66-
To learn more about the extensions and how to configure the oneAPI environment, see
67-
[Using Visual Studio Code with Intel&reg; oneAPI Toolkits User Guide](https://software.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
74+
To learn more about the extensions and how to configure the oneAPI environment, see the
75+
[Using Visual Studio Code with Intel® oneAPI Toolkits User Guide](https://www.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
6876

6977
### On Linux*
70-
Perform the following steps:
71-
1. Build the program using the following `cmake` commands.
78+
1. Change to the sample directory.
79+
2. Build the program.
7280
```
73-
$ mkdir build
74-
$ cd build
75-
$ cmake ..
76-
$ make -j
81+
mkdir build
82+
cd build
83+
cmake ..
84+
make
85+
```
86+
By default, executable builds for a kernel with direct global memory usage. You can build the kernel with shared local memory (SLM) buffers.
87+
```
88+
cmake -DSHARED_KERNEL=1 ..
89+
make
7790
```
78-
By default, executable is build with kernel with direct global memory usage. You can build the kernel with shared local memory (SLM) buffers with the following:
79-
```
80-
cmake -DSHARED_KERNEL=1 ..
81-
make -j
82-
```
83-
2. Run the program :
84-
```
85-
make run
86-
```
87-
> **Note**: for selecting CPU as a SYCL device, use `make run_cpu`.
88-
8991
If an error occurs, you can get more details by running `make` with
9092
the `VERBOSE=1` argument:
9193
```
9294
make VERBOSE=1
9395
```
96+
### On Windows*
97+
**Using Visual Studio***
9498

95-
#### Troubleshooting
96-
If you receive an error message, troubleshoot the problem using the Diagnostics Utility for Intel&reg; oneAPI Toolkits, which provides system checks to find missing
97-
dependencies and permissions errors. See [Diagnostics Utility for Intel&reg; oneAPI Toolkits User Guide](https://www.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html).
99+
Build the program using **Visual Studio 2017** or newer.
100+
1. Change to the sample directory.
101+
2. Right-click on the solution file and open the solution in the IDE.
102+
3. Right-click on the project in **Solution Explorer** and select **Rebuild**.
103+
4. From the top menu, select **Debug** > **Start without Debugging**. (This runs the program.)
98104

99-
### On Windows* Using Visual Studio* Version 2017 or Newer
100-
- Build the program using VS2017 or VS2019
101-
- Right-click on the solution file and open using either VS2017 or VS2019 IDE.
102-
- Right-click on the project in Solution Explorer and select Rebuild.
103-
- From the top menu, select Debug -> Start without Debugging.
105+
**Using MSBuild**
106+
1. Open "x64 Native Tools Command Prompt for VS2017" or "x64 Native Tools Command Prompt for VS2019" or whatever is appropriate for your Visual Studio* version.
107+
2. Change to the sample directory.
108+
3. Run the following command: `MSBuild iso3dfd_dpcpp.sln /t:Rebuild /p:Configuration="Release"`
104109

105-
- Build the program using MSBuild
106-
- Open "x64 Native Tools Command Prompt for VS2017" or "x64 Native Tools Command Prompt for VS2019"
107-
- Run the following command: `MSBuild iso3dfd_dpcpp.sln /t:Rebuild /p:Configuration="Release"`
110+
#### Troubleshooting
111+
If you receive an error message, troubleshoot the problem using the **Diagnostics Utility for Intel® oneAPI Toolkits**. The diagnostic utility provides configuration and system checks to help find missing dependencies, permissions errors, and other issues. See the [Diagnostics Utility for Intel® oneAPI Toolkits User Guide](https://www.intel.com/content/www/us/en/develop/documentation/diagnostic-utility-user-guide/top.html) for more information on using the utility.
112+
113+
## Run the `ISO3DFD` Program
114+
### Configurable Application Parameters
115+
You can specify input parameters for the program. Different devices and variants require different inputs.
116+
117+
Usage: `iso3dfd.exe n1 n2 n3 b1 b2 b3 iterations [omp|sycl] [gpu|cpu]`
118+
119+
|Parameter | Description
120+
|:--- |:---
121+
|`n1 n2 n3` | Grid sizes for the stencil.
122+
|`b1 b2 b3` | (OMP) Cache block sizes for cpu openmp version.
123+
|`b1 b2` | (SYCL) Thread block sizes in X and Y dimensions for SYCL version.
124+
|`b3` | (SYCL) Size of slice of work in Z dimension for SYCL version.
125+
|`iterations` | Number of timesteps.
126+
|`omp\|sycl` | (Optional) Run the OpenMP or the SYCL variant. Default to both for validation.
127+
|`gpu\|cpu` | (Optional) Device for the SYCL version; default to GPU if available. If a GPU is not available, the program runs on the CPU.
128+
129+
### On Linux
130+
1. Run the program.
131+
```
132+
make run
133+
```
134+
Alternatively, you can select CPU as a SYCL device by using `make run_cpu`.
108135

136+
### On Windows
137+
1. Change to the output directory.
138+
2. Specify the input values, and run the program.
139+
```
140+
iso3dfd_dpcpp.exe 256 256 256 32 8 64 10 gpu
141+
```
109142

110-
### Run Samples in Intel&reg; DevCloud
111-
If running a sample in the Intel&reg; DevCloud, you must specify the compute node (CPU, GPU, FPGA) and whether to run in batch or interactive mode. For more information, see the Intel&reg; oneAPI Base Toolkit [Get Started Guide](https://devcloud.intel.com/oneapi/get_started/).
143+
### Build and Run the `ISO3DFD` Sample in Intel® DevCloud (Optional)
144+
When running a sample in the Intel® DevCloud, you must specify the compute node (CPU, GPU, FPGA) and whether to run in batch or interactive mode. You can specify a GPU node using a single line script.
112145

146+
```
147+
qsub -I -l nodes=1:gpu:ppn=2 -d .
148+
```
113149

114-
## Run the Sample
115-
1. Run the sample.
116-
```
117-
make run
118-
```
119-
### Application Parameters
120-
You can modify the ISO3DFD parameters from the command line with configurable application parameters:
150+
- `-I` (upper case I) requests an interactive session.
151+
- `-l nodes=1:gpu:ppn=2` (lower case L) assigns one full GPU node.
152+
- `-d .` makes the current folder as the working directory for the task.
121153

122-
Usage: `src/iso3dfd.exe n1 n2 n3 b1 b2 b3 Iterations [omp|sycl] [gpu|cpu]`
154+
For more information on how to specify compute nodes read, [Launch and manage jobs](https://devcloud.intel.com/oneapi/documentation/job-submission/) in the Intel® DevCloud for oneAPI Documentation.
123155

124-
- `n1 n2 n3`: Grid sizes for the stencil.
125-
- `b1 b2 b3`: cache block sizes for cpu openmp version.
126-
OR
127-
- `b1 b2`: Thread block sizes in X and Y dimensions for SYCL version.
128-
- and `b3`: size of slice of work in Z dimension for SYCL version.
129-
- `Iterations`: Number of timesteps.
130-
- `[omp|sycl]`: (Optional) Run the OpenMP or the SYCL variant. Default uses both for validation.
131-
- `[gpu|cpu]`: (Optional) Device to run the SYCL version. Default uses the GPU if available. if GPU is not available then fallback to CPU.
156+
For more information on using Intel® DevCloud, see the Intel® oneAPI Base Toolkit [Get Started Guide](https://devcloud.intel.com/oneapi/get_started/).
132157

133-
### Example of Output
158+
## Example Output
134159
```
135160
Grid Sizes: 256 256 256
136161
Memory Usage: 230 MB
@@ -165,9 +190,9 @@ bytes : 3.36952 GBytes/s
165190
Final wavefields from SYCL device and CPU are equivalent: Success
166191
--------------------------------------
167192
```
168-
## License
169193

194+
## License
170195
Code samples are licensed under the MIT license. See
171196
[License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt) for details.
172197

173-
Third party program Licenses can be found here: [third-party-programs.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/third-party-programs.txt).
198+
Third party program Licenses can be found here: [third-party-programs.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/third-party-programs.txt).

0 commit comments

Comments
 (0)