Skip to content

Commit 8a2d908

Browse files
jkinskyjkinsky
authored
Updated ISO2DFD README.md file (oneapi-src#1044)
Restructured this sample to match the new sample, updated some branding, added some sections, and included Windows information as included in the samples.json file.
1 parent d71a196 commit 8a2d908

File tree

1 file changed

+107
-77
lines changed
  • DirectProgramming/DPC++/StructuredGrids/iso2dfd_dpcpp

1 file changed

+107
-77
lines changed

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

Lines changed: 107 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,126 +1,152 @@
11
# `ISO2DFD` Sample
2+
The `ISO2DFD` sample demonstrates two-dimensional finite-difference wave propagation in isotropic media. The sample is a two-dimensional stencil to simulate a wave propagating in a 2D isotropic medium, and the code illustrates the basics of SYCL* code using direct programming.
23

3-
The ISO2DFD sample refers to Two-Dimensional Finite-Difference Wave Propagation in Isotropic Media. It is a two-dimensional stencil to simulate a wave propagating in a 2D isotropic medium and illustrates the basics of SYCL*-compliant code using direct programming.
4-
5-
> **Note**: You can find a complete code walk-through of this sample at [Code Sample: Two-Dimensional Finite-Difference Wave Propagation in Isotropic Media (ISO2DFD) – An Intel® oneAPI DPC++ Compiler Example](https://software.intel.com/en-us/articles/code-sample-two-dimensional-finite-difference-wave-propagation-in-isotropic-media-iso2dfd).
6-
7-
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.
8-
9-
| Property | Description
10-
|:--- |:---
11-
| What you will learn | How to offload the computation to GPU using Intel® oneAPI DPC++/C++ Compiler
12-
| Time to complete | 10 minutes
4+
| Area | Description
5+
|:--- |:---
6+
| What you will learn | How to offload complex computation to a GPU
7+
| Time to complete | 10 minutes
138

149
## Purpose
10+
ISO2DFD is a finite difference stencil kernel for solving the 2D acoustic isotropic wave equation. The sample uses a Partial Differential Equation (PDE), with a finite-difference method, to illustrate the essential elements of SYCL* queues, buffers, accessors, and kernels.
1511

16-
ISO2DFD is a finite difference stencil kernel for solving the 2D acoustic isotropic wave equation. In
17-
this sample, we chose the problem of solving a Partial Differential Equation (PDE), using a
18-
finite-difference method, to illustrate the essential elements of SYCL* queues, buffers, accessors, and kernels. Use it as an entry point to start SYCL* programming or as a
19-
proxy to develop or better understand complicated code for similar problems.
12+
> **Note**: You can find a complete code walk-through of this sample at [Code Sample: Two-Dimensional Finite-Difference Wave Propagation in Isotropic Media (ISO2DFD)](https://software.intel.com/en-us/articles/code-sample-two-dimensional-finite-difference-wave-propagation-in-isotropic-media-iso2dfd).
2013
21-
The sample will explicitly run on the GPU as well as CPU to calculate a
22-
result. The output will include GPU device name. The results from the two devices are compared, and if the sample ran correctly report a success message. The output of the wavefield can be plotted using the SU Seismic processing library, which has utilities to display seismic wavefields. You can download the processing library from [John Stockwell’s SeisUnix GitHub](https://github.com/JohnWStockwellJr/SeisUnix).
14+
You can use this sample code as an entry point to start SYCL* programming or as a proxy to develop or better understand complicated code for similar problems.
2315

24-
## Prequisites
25-
26-
| Optimized for | Description
27-
|:--- |:---
28-
| OS | Ubuntu* 18.04
29-
| Hardware | Skylake with GEN9 or newer
30-
| Software | Intel® oneAPI DPC++/C++ Compiler
16+
## Prerequisites
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-
34-
SYCL implementation explained.
35-
24+
The sample demonstrates several SYCL implementations.
3625
- SYCL queues (including device selectors and exception handlers).
3726
- SYCL buffers and accessors.
3827
- The ability to call a function inside a kernel definition and pass accessor arguments as pointers. A function called inside the kernel performs a computation (it updates a grid point specified by the global ID variable) for a single time step.
3928

40-
## Build the `iso2dfd` Program for CPU and GPU
29+
The sample runs on the GPU and CPU to calculate a result. The results from the two devices are compared. If the sample ran correctly, the program reports success.
30+
31+
The output includes the GPU device name.
4132

33+
## Set Environment Variables
34+
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.
35+
36+
## Build the `ISO2DFD` Program for CPU and GPU
4237
> **Note**: If you have not already done so, set up your CLI
43-
> environment by sourcing the `setvars` script located in
44-
> the root of your oneAPI installation.
38+
> environment by sourcing the `setvars` script in the root of your oneAPI installation.
4539
>
46-
> Linux:
40+
> Linux*:
4741
> - For system wide installations: `. /opt/intel/oneapi/setvars.sh`
48-
> - For private installations: `. ~/intel/oneapi/setvars.sh`
42+
> - For private installations: ` . ~/intel/oneapi/setvars.sh`
43+
> - For non-POSIX shells, like csh, use the following command: `bash -c 'source <install-dir>/setvars.sh ; exec csh'`
4944
>
50-
> Windows:
45+
> Windows*:
5146
> - `C:\Program Files(x86)\Intel\oneAPI\setvars.bat`
47+
> - Windows PowerShell*, use the following command: `cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'`
5248
>
53-
>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).
54-
49+
> 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).
5550
5651
### Include Files
52+
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.
5753

58-
The include folder is located at `%ONEAPI_ROOT%\dev-utilities\latest\include` on your development system.
54+
>**Note**: You can get the common resources from the [oneAPI-samples](https://github.com/oneapi-src/oneAPI-samples/tree/master/common) GitHub repository.
5955
60-
### Use Visual Studio Code* (Optional)
61-
62-
You can use Visual Studio Code (VS Code) extensions to set your environment, create launch configurations, and browse and download samples.
56+
### Use Visual Studio Code* (VS Code) (Optional)
57+
You can use Visual Studio Code* (VS Code) extensions to set your environment,
58+
create launch configurations, and browse and download samples.
6359

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

70-
To learn more about the extensions and how to configure the oneAPI environment, see
71-
[Using Visual Studio Code with Intel® oneAPI Toolkits User Guide](https://software.intel.com/content/www/us/en/develop/documentation/using-vs-code-with-intel-oneapi/top.html).
66+
To learn more about the extensions and how to configure the oneAPI environment, see the
67+
[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).
7268

7369
### On Linux*
74-
Perform the following steps:
75-
1. Build the program using the following `cmake` commands.
70+
1. Change to the sample directory.
71+
1. Build the program.
7672
```
77-
cd iso2dfd_dpcpp &&
78-
mkdir build &&
79-
cd build &&
80-
cmake .. &&
81-
make -j
82-
```
83-
2. Run the program.
84-
```
85-
make run
86-
```
73+
mkdir build
74+
cd build
75+
cmake ..
76+
make -j
77+
```
78+
8779
If an error occurs, you can get more details by running `make` with
8880
the `VERBOSE=1` argument:
8981
```
9082
make VERBOSE=1
9183
```
9284

93-
#### Troubleshooting
94-
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
95-
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).
85+
### On Windows*
86+
**Using Visual Studio***
9687

97-
### On Windows* Using Visual Studio* Version 2017 or Newer
98-
- Build the program using VS2017 or VS2019.
99-
- Right-click on the solution file and open using either VS2017 or VS2019 IDE.
100-
- Right-click on the project in Solution Explorer and select Rebuild.
101-
- From the top menu, select Debug -> Start without Debugging.
88+
Build the program using **Visual Studio 2017** or newer.
89+
1. Change to the sample directory.
90+
2. Right-click on the solution file and open the solution in the IDE.
91+
3. Right-click on the project in **Solution Explorer** and select **Rebuild**.
92+
4. From the top menu, select **Debug** > **Start without Debugging**. (This runs the program.)
10293

103-
### Run Samples in Intel&reg; DevCloud
104-
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/).
94+
**Using MSBuild**
95+
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.
96+
2. Change to the sample directory.
97+
3. Run the following command: `MSBuild iso2dfd.sln /t:Rebuild /p:Configuration="Release"`
10598

106-
## Run the Sample
99+
#### Troubleshooting
100+
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.
101+
102+
103+
## Run the `ISO2DFD` Sample
107104
### Application Parameters
105+
The program requires grid size and time steps to execute.
106+
```
107+
program <n1> <n2> <iterations>
108+
```
109+
where:
110+
| Parameter | Description
111+
|:--- |:---
112+
|`n1 n2` | Grid size for the stencil. `n1` is X (rows) and `n2` is Y (columns). Use `n1` = **1000** and `n2` = **1000** for results that match the output below.
113+
| `iterations` |Number of timesteps. Use `iterations` = **2000** for results that match the output below.
108114

109-
You can execute the code with different parameters.
115+
To specify a grid size of 1000x1000 and 2000 time steps iterations, you would use the following command: `iso2dfd 1000 1000 2000`.
110116

111-
Usage: `./iso2dfd n1 n2 Iterations`
117+
### On Linux
118+
1. Run the program.
119+
```
120+
make run
121+
```
122+
2. Clean the project files. (Optional)
123+
```
124+
make clean
125+
```
126+
### On Windows
127+
1. Change to the output directory.
128+
2. Specify the input parameters, and run the program.
129+
```
130+
iso2dfd.exe 1000 1000 2000
131+
```
112132
113-
Where:
114-
- `n1 n2`: Grid sizes for the stencil
115-
- `Iterations`: Number of timesteps.
133+
### Build and Run the `ISO2DFD` Sample in Intel® DevCloud (Optional)
134+
<This is the short version. Use ONLY the short version OR the long version NOT both.>
135+
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.
116136
117-
For example the following command will run the iso2dfd executable using a 1000x1000 grid size and it will iterate over 2000 time steps.
118137
```
119-
./iso2dfd 1000 1000 2000
138+
qsub -I -l nodes=1:gpu:ppn=2 -d .
120139
```
121-
> **Note**: You can find graphical output for sample execution in [Code Sample: Two-Dimensional Finite-Difference Wave Propagation in Isotropic Media (ISO2DFD) – An Intel&reg; oneAPI DPC++ Compiler Example](https://software.intel.com/en-us/articles/code-sample-two-dimensional-finite-difference-wave-propagation-in-isotropic-media-iso2dfd).
122140
123-
### Example of Output
141+
- `-I` (upper case I) requests an interactive session.
142+
- `-l nodes=1:gpu:ppn=2` (lower case L) assigns one full GPU node.
143+
- `-d .` makes the current folder as the working directory for the task.
144+
145+
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.
146+
147+
For more information on using Intel® DevCloud, see the Intel® oneAPI Base Toolkit [Get Started Guide](https://devcloud.intel.com/oneapi/get_started/).
148+
149+
### Example Output
124150
```
125151
Initializing ...
126152
Grid Sizes: 1000 1000
@@ -139,8 +165,12 @@ CPU time: 8846 ms
139165
Final wavefields from device and CPU are equivalent: Success
140166
Final wavefields (from device and CPU) written to disk
141167
Finished.
142-
[100%] Built target run
143168
```
169+
170+
If you run the program on Linux, you can use the generated .bin files to plot the wave field output using the SU seismic processing library, which is part of the Seismic Un*x Package. The library contains utilities to display seismic wave fields, and the processing library is available from [John Stockwell's SeisUnix](https://github.com/JohnWStockwellJr/SeisUnix) GitHub Repository.
171+
172+
You can find graphical output examples for the program at [Code Sample: Two-Dimensional Finite-Difference Wave Propagation in Isotropic Media (ISO2DFD)](https://software.intel.com/en-us/articles/code-sample-two-dimensional-finite-difference-wave-propagation-in-isotropic-media-iso2dfd).
173+
144174
## License
145175
Code samples are licensed under the MIT license. See
146176
[License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt) for details.

0 commit comments

Comments
 (0)