Skip to content

Commit d71a196

Browse files
jkinskyjkinsky
authored
Updated 1dHeatTransfer README.md (oneapi-src#1042)
Updated to match new template structure. Added Windows information. Fixed formatting issues. Updated devcloud information.
1 parent a144114 commit d71a196

File tree

1 file changed

+118
-87
lines changed
  • DirectProgramming/DPC++/StructuredGrids/1d_HeatTransfer

1 file changed

+118
-87
lines changed

‎DirectProgramming/DPC++/StructuredGrids/1d_HeatTransfer/README.md

Lines changed: 118 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,158 +1,189 @@
11
# `1D-Heat-Transfer` Sample
22

3-
This code sample demonstrates the simulation of a one-dimensional heat transfer process using SYCL*. Kernels in this example are implemented as a discretized differential equation with the second derivative in space and the first derivative in time.
3+
This `1D-Heat-Transfer` sample demonstrates the simulation of a one-dimensional heat transfer process. Kernels in this example are implemented as a discretized differential equation with the second derivative in space and the first derivative in time.
44

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-
| Property | Description
8-
|:--- |:---
9-
| What you will learn | How to simulate 1D Heat Transfer using Intel® oneAPI DPC++ Compiler
10-
| Time to complete | 10 minutes
5+
| Area | Description
6+
|:--- |:---
7+
| What you will learn | How to simulate 1D Heat Transfer using SYCL*
8+
| Time to complete | 10 minutes
119

1210

1311
## Purpose
12+
This `1D-Heat-Transfer` sample is an application that simulates the heat
13+
propagation on a one-dimensional isotropic and homogeneous medium. The code sample includes both parallel and serial calculations of heat
14+
propagation.
1415

15-
1D-Heat-Transfer is a SYCL*-compliant application that simulates the heat
16-
propagation on a one-dimensional isotropic and homogeneous medium. The
17-
following equation is used in the simulation of heat propagation:
16+
The following equation is used in the simulation of heat propagation:
1817

19-
$dU/dt = k * d^2U/dx^2$
18+
$
19+
dU/dt = k * d^2U/dx^2
20+
$
2021

21-
Where:
22+
where:
2223
- $dU/dt$ is the rate of change of temperature at a point.
23-
- $k$ is the thermal diffusivity.
24+
- k is the thermal diffusivity.
2425
- $d^2U/dx^2$ is the second spatial derivative.
2526

26-
or
27+
or:
2728

28-
$U(i) = C * (U(i+1) - 2 * U(i) + U(i-1)) + U(i)$
29+
$
30+
U(i) = C * (U(i+1) - 2 * U(i) + U(i-1)) + U(i)
31+
$
2932

30-
Where:
33+
where:
3134
- constant $C = k * dt / (dx * dx)$
3235

33-
The code sample includes both parallel and serial calculations of heat
34-
propagation. The code sample attempts to execute on an
35-
available GPU and will fallback to the system CPU if a compatible GPU is
36-
not detected. The results are stored in a file.
37-
3836
## Prerequisites
39-
4037
| Optimized for | Description
4138
|:--- |:---
42-
| OS | Ubuntu* 18.04
39+
| OS | Ubuntu* 18.04 <br> Windows* 10
4340
| Hardware | Skylake with GEN9 or newer
44-
| Software | Intel&reg; oneAPI DPC++/C++ Compiler
41+
| Software | Intel® oneAPI DPC++/C++ Compiler
4542

4643
## Key Implementation Details
47-
4844
The basic SYCL* implementation explained in the code includes a device
4945
selector, buffer, accessor, USM allocation, kernel, and command
5046
groups.
5147

52-
## Build the 1d_HeatTransfer Program for CPU and GPU
48+
The program attempts to offload the computations to a GPU first. If the program cannot detect a compatible GPU, the program runs on the CPU (host device).
49+
50+
## Set Environment Variables
51+
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.
52+
53+
>**Note**: For comprehensive information about oneAPI programming, see the [Intel&reg; oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programming-guide). (Use search or the table of contents to find relevant information quickly.)
5354
55+
## Build the `1D-Heat-Transfer` Program for CPU and GPU
5456
> **Note**: If you have not already done so, set up your CLI
55-
> environment by sourcing the `setvars` script located in
56-
> the root of your oneAPI installation.
57+
> environment by sourcing the `setvars` script in the root of your oneAPI installation.
5758
>
58-
> Linux:
59+
> Linux*:
5960
> - For system wide installations: `. /opt/intel/oneapi/setvars.sh`
60-
> - For private installations: `. ~/intel/oneapi/setvars.sh`
61+
> - For private installations: ` . ~/intel/oneapi/setvars.sh`
62+
> - For non-POSIX shells, like csh, use the following command: `bash -c 'source <install-dir>/setvars.sh ; exec csh'`
6163
>
62-
> Windows:
64+
> Windows*:
6365
> - `C:\Program Files(x86)\Intel\oneAPI\setvars.bat`
66+
> - Windows PowerShell*, use the following command: `cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'`
6467
>
65-
>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).
66-
68+
> 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).
6769
6870
### Include Files
71+
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.
6972

70-
The include folder is located at
71-
`%ONEAPI_ROOT%\dev-utilities\latest\include` on your development
72-
system".
73-
73+
>**Note**: You can get the common resources from the [oneAPI-samples](https://github.com/oneapi-src/oneAPI-samples/tree/master/common) GitHub repository.
7474
75-
### Use Visual Studio Code* (Optional)
7675

77-
You can use Visual Studio Code (VS Code) extensions to set your environment, create launch configurations, and browse and download samples.
76+
### Use Visual Studio Code* (VS Code) (Optional)
77+
You can use Visual Studio Code* (VS Code) extensions to set your environment,
78+
create launch configurations, and browse and download samples.
7879

7980
The basic steps to build and run a sample using VS Code include:
80-
- Download a sample using the extension **Code Sample Browser for Intel&reg; oneAPI Toolkits**.
81-
- Configure the oneAPI environment with the extension **Environment Configurator for Intel&reg; oneAPI Toolkits**.
82-
- Open a Terminal in VS Code (**Terminal>New Terminal**).
83-
- Run the sample in the VS Code terminal using the instructions below.
84-
85-
To learn more about the extensions and how to configure the oneAPI environment, see
86-
[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).
81+
1. Configure the oneAPI environment with the extension **Environment Configurator for Intel® oneAPI Toolkits**.
82+
2. Download a sample using the extension **Code Sample Browser for Intel® oneAPI Toolkits**.
83+
3. Open a terminal in VS Code (**Terminal > New Terminal**).
84+
4. Run the sample in the VS Code terminal using the instructions below.
8785

86+
To learn more about the extensions and how to configure the oneAPI environment, see the
87+
[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).
8888

8989
### On Linux*
90-
1. Build the program using the following `cmake` commands.
91-
```
92-
$ cd 1d_HeatTransfer
93-
$ mkdir build
94-
$ cd build
95-
$ cmake ..
96-
$ make -j
97-
```
98-
2. Run the program
90+
1. Change to the sample directory.
91+
2. Build the program.
9992
```
100-
$ make run
93+
mkdir build
94+
cd build
95+
cmake ..
96+
make -j
10197
```
98+
> **Note**: The `make -j` flag allows multiple jobs simultaneously.
99+
102100
If an error occurs, you can get more details by running `make` with
103101
the `VERBOSE=1` argument:
104102
```
105103
make VERBOSE=1
106104
```
107-
#### Troubleshooting
108-
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
109-
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).
110105

111-
### On Windows* Using Visual Studio* Version 2017 or Newer
112-
- Build the program using VS2017 or VS2019.
113-
- Right-click on the solution file and open using either VS2017 or VS2019 IDE.
114-
- Right-click on the project in Solution Explorer and select Rebuild.
115-
- From the top menu, select Debug -> Start without Debugging.
106+
### On Windows*
107+
**Using Visual Studio***
116108

117-
- Build the program using MSBuild.
118-
- Open "x64 Native Tools Command Prompt for VS2017" or "x64 Native Tools Command Prompt for VS2019"
119-
- Run the following command: `MSBuild 1d_HeatTransfer.sln /t:Rebuild /p:Configuration="Release"`
109+
Build the program using **Visual Studio 2017** or newer.
110+
1. Change to the sample directory.
111+
2. Right-click on the solution file and open the solution in the IDE.
112+
3. Right-click on the project in **Solution Explorer** and select **Rebuild**.
113+
4. From the top menu, select **Debug** > **Start without Debugging**. (This runs the program.)
120114

121-
### Run Samples in Intel&reg; DevCloud
122-
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/).
115+
**Using MSBuild**
116+
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.
117+
2. Change to the sample directory.
118+
3. Run the following command: `MSBuild 1d_HeatTransfer.sln /t:Rebuild /p:Configuration="Release"`
123119

124-
## Run the Sample
125-
### Application Parameters
120+
#### Troubleshooting
121+
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.
126122

127-
Usage: `1d_HeatTransfer <n> <i>`
128123

129-
Where:
130-
- `n` is the number of points you want to simulate the heat transfer.
131-
- `i` is the number of timesteps in the simulation.
124+
## Run the `1D-Heat-Transfer` Program
125+
### Application Parameters
126+
The program requires two inputs. General usage syntax is as follows:
127+
128+
`1d_HeatTransfer <n> <i>`
132129

133-
To simulate 100 points for 1000 timesteps: `./1d_HeatTransfer 100 1000`
130+
| Input | Description
131+
|:--- |:---
132+
| `n` | The number of points you want to simulate the heat transfer.
133+
| `i` | The number of timesteps in the simulation.
134134

135-
The sample performs the computation serially on CPU, using SYCL* buffers and USM. The results are compared against the serial version and saved to `usm_error_diff.txt` and
136-
`buffer_error_diff.txt`. If the results match, the application will
135+
The sample performs the computation serially on CPU using buffers and USM. The parallel results are compared to serial version. The output of the comparisons is saved to `usm_error_diff.txt` and
136+
`buffer_error_diff.txt` in the output directory. If the results match, the application will
137137
display a `PASSED!` message.
138138

139-
### Example of Output
139+
### On Linux
140+
1. Run the program
141+
```
142+
$ make run
143+
```
144+
2. Clean project files. (Optional)
145+
```
146+
make clean
147+
```
148+
149+
### On Windows
150+
1. Change to the output directory.
151+
2. Specify the input values, and run the program.
152+
```
153+
1d_HeatTransfer 100 1000
154+
```
155+
156+
### Build and Run the `1D-Heat-Transfer` Sample in Intel® DevCloud (Optional)
157+
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.
158+
159+
```
160+
qsub -I -l nodes=1:gpu:ppn=2 -d .
161+
```
162+
163+
- `-I` (upper case I) requests an interactive session.
164+
- `-l nodes=1:gpu:ppn=2` (lower case L) assigns one full GPU node.
165+
- `-d .` makes the current folder as the working directory for the task.
166+
167+
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.
168+
169+
For more information on using Intel® DevCloud, see the Intel&reg; oneAPI Base Toolkit [Get Started Guide](https://devcloud.intel.com/oneapi/get_started/).
170+
171+
## Example Output
140172
```
141-
$ make run
142-
[100%] Built target 1d_HeatTransfer
143173
Number of points: 100
144174
Number of iterations: 1000
145175
Using buffers
146-
Kernel runs on Intel(R) Core(TM) i5-7300U CPU @ 2.60GHz
147-
Elapsed time: 0.439238 sec
176+
Kernel runs on Intel(R) UHD Graphics P630 [0x3e96]
177+
Elapsed time: 0.506778 sec
148178
PASSED!
149179
Using USM
150-
Kernel runs on Intel(R) Core(TM) i5-7300U CPU @ 2.60GHz
151-
Elapsed time: 0.193435 sec
180+
Kernel runs on Intel(R) UHD Graphics P630 [0x3e96]
181+
Elapsed time: 0.00926689 sec
152182
PASSED!
153-
[100%] Built target run
154-
$
155183
```
184+
185+
The parallel to serial comparisons are saved to `usm_error_diff.txt` and `buffer_error_diff.txt` in the output directory.
186+
156187
## License
157188
Code samples are licensed under the MIT license. See
158189
[License.txt](https://github.com/oneapi-src/oneAPI-samples/blob/master/License.txt) for details.

0 commit comments

Comments
 (0)