Skip to content

Update particle diffusion README.md #1047

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

Merged
merged 1 commit into from
Aug 24, 2022
Merged

Update particle diffusion README.md #1047

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
203 changes: 109 additions & 94 deletions DirectProgramming/DPC++/StructuredGrids/particle-diffusion/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,150 +1,166 @@
# `Water Molecule Diffusion` Sample
# `Particle Diffusion` Sample
The `Particle Diffusion` code sample implements a simple example of a Monte Carlo simulation of water molecule diffusion in tissue. This kind of computational experiment can be used to simulate the acquisition of a diffusion signal for dMRI.

This code sample implements a simple example of a Monte Carlo simulation of water molecule diffusion in tissue. This kind of computational experiment can be used to simulate the acquisition of a diffusion signal for dMRI.

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.

| Property | Description
|:--- |:---
| What you will learn | How to offload the computation to GPU using the Intel® oneAPI DPC++/C++ Compiler
| Time to complete | 20 minutes
| Area | Description
|:--- |:---
| What you will learn | How to offload complex computation to a GPU
| Time to complete | 20 minutes

## Purpose
The simulation model consists of water molecules moving through a 2D array of cells in a tissue sample (water molecule diffusion). The sample uses a uniform rectilinear 2D array of digital cells. The cells are spaced regularly along each direction and are represented by circles.

The simulation model consists of water molecules moving through a 2D array of cells in a tissue sample (water molecule diffusion). In this code sample, we use a uniform rectilinear 2D array of digital cells, where cells are spaced regularly along each direction and are represented by circles.

Water molecule diffusion is simulated by defining a number of particles P (simulated water molecules) at random positions in the grid, followed by random walks of these particles in the ensemble of cells in the grid. During the random walks, particles can move randomly inside or outside simulated cells. The positions of these particles at every time step in the simulation, the number of times they go through a cell membrane (in/out), and the time every particle spends inside and outside cells can be recorded. These measurements are a simple example of useful information that can be used to simulate an MR signal.

> **Note**: You can find more information and a walk through for this sample at [Code Sample: Particle Diffusion – An Intel® oneAPI DPC++/C++ Compiler Example](https://www.intel.com/content/www/us/en/developer/articles/code-sample/oneapi-dpcpp-compiler-example-particle-diffusion.html).
The sample code simulates water molecule diffusion by defining a number of particles P (simulated water molecules) at random positions in the grid. The code randomly walks the particles in the ensemble of cells in the grid. During the random walks, particles can move randomly inside or outside simulated cells. The program records the positions of the particles at every time step in the simulation, the number of times they go through a cell membrane (in or out), and the amount of time every particle spends inside and outside cells.

Performance number tabulation, if applicable.
These measurements are a simple example of useful information needed for simulating a magnetic resonance (MR) signal.

| motionsim sample | Performance data
|:--- |:---
| Scalar baseline -O2 | 1.0
| SYCL |
| OpenMP offload |
> **Note**: You can find more information about this sample and a walk-through at [Code Sample: Particle Diffusion – An Intel® oneAPI DPC++/C++ Compiler Example](https://www.intel.com/content/www/us/en/developer/articles/code-sample/oneapi-dpcpp-compiler-example-particle-diffusion.html).

## Prerequisites
| Optimized for | Description
|:--- |:---
| OS | Ubuntu* 18.04 <br>Windows* 10 <br>Windows* Server 2017
| Hardware | Kaby Lake with Gen9 or newer
| Software | Intel&reg; oneAPI DPC++/C++ Compiler
| Software | Intel® oneAPI DPC++/C++ Compiler

## Key Implementation Details

SYCL* implementation explained in this sample includes:
SYCL* concepts explained in this sample include:
- SYCL* queues (including device selectors and exception handlers).
- SYCL buffers and accessors.
- The ability to call a function inside a kernel definition and pass accessor arguments as pointers.
- Optimization using API-based programming and Atomic Functions.

SYCL implementation is explained in further detail in the source code.
The SYCL implementation is explained in the source code.

The sample uses the Intel® Math Kernel Library (Intel® MKL) to generate random numbers on the CPU and device. Precise generators are used within this library to ensure that the numbers generated on the CPU and device are relatively equivalent (relative accuracy 10E-07).

Intel&reg; Math Kernel Library (Intel&reg; MKL) is used to generate random numbers on the CPU and device. Precise generators are used within this library to ensure that the numbers generated on the CPU and device are relatively equivalent (relative accuracy 10E-07).
>**Note**: For comprehensive information about oneAPI programming, see the [Intel® oneAPI Programming Guide](https://software.intel.com/en-us/oneapi-programming-guide). (Use search or the table of contents to find relevant information quickly.)

## Build the `particle-diffusion` Program for CPU and GPU
## Set Environment Variables
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.

## Build the `Particle Diffusion` Program for CPU and GPU
> **Note**: If you have not already done so, set up your CLI
> environment by sourcing the `setvars` script located in
> the root of your oneAPI installation.
> environment by sourcing the `setvars` script in the root of your oneAPI installation.
>
> Linux:
> Linux*:
> - For system wide installations: `. /opt/intel/oneapi/setvars.sh`
> - For private installations: `. ~/intel/oneapi/setvars.sh`
> - For private installations: ` . ~/intel/oneapi/setvars.sh`
> - For non-POSIX shells, like csh, use the following command: `bash -c 'source <install-dir>/setvars.sh ; exec csh'`
>
> Windows:
> Windows*:
> - `C:\Program Files(x86)\Intel\oneAPI\setvars.bat`
> - Windows PowerShell*, use the following command: `cmd.exe "/K" '"C:\Program Files (x86)\Intel\oneAPI\setvars.bat" && powershell'`
>
>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).
> 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).

### Include Files
The include folder is located at `%ONEAPI_ROOT%\dev-utilities\latest\include` on your
development system.
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.

### Use Visual Studio Code* (Optional)
>**Note**: You can get the common resources from the [oneAPI-samples](https://github.com/oneapi-src/oneAPI-samples/tree/master/common) GitHub repository.

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

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

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

## Build the Sample
### On Linux*
1. Change to the sample directory.
2. Build the program.
```
mkdir build
cd build
cmake ..
make
```

1. Change to the particle diffusion directory.
### On Windows*
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.
2. Change to the sample directory.
3. Build the program.
```
nmake
```
>**Note**: This will run the program too.

## Run the `Particle Diffusion` Program
### Configurable Application Parameters
The following table describes each command line parameter you can use.

|Flag and Argument |Description |Range of Possible Values |Default
|:--- |:--- |:--- |:---
|`-i num_iterations` | Number of iterations | [1, &#8734;] | 10000
|`-p num_particles` | Number of particles | [1, &#8734;] | 256
|`-g grid_size` | Size of square grid | [1, &#8734;] | 22
|`-r rng_seed` | Random number generator seed | [-&#8734;, &#8734;] | 777
|`-c cpu_flag` | Turns cpu comparison on/off | [1 \| 0] | 0
|`-o output_flag` | Turns grid output on/off | [1 \| 0] | 1
|`-h` | Help message. | |

#### Parameter Rules
- If you do not specify parameters, the program will use the defaults for all parameters.
- If you do not specify a specific parameter, the program will use the default value for that parameter.
- If you specify a `grid_size` greater than **44**, the program will not print the grid even if the grid output flag is on.
- The input flags apply to Linux only. Pass values without flags on Windows.
- Enter `motionsim.exe -h` to display help text and exit the program.

Example usage with default values on Linux:
```
$ cd particle-diffusion
motionsim.exe -i 10000 -p 256 -g 22 -r 777 -c 0 -o 1
```
2. Build the program.
Example usage with default values on Windows:
```
$ mkdir build
$ cd build
$ cmake ..
$ make -s -j
motionsim.exe 10000 256 22 777 0 1
```

### On Windows*
1. Use `nmake` to build the sample.

> **Note**: `nmake clean` removes temporary files.

### Run Samples in Intel&reg; DevCloud
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/).

## Run the Sample
### On Linux
1. Run the program.
```
make run
```
Alternatively, specify the input values, and run the program directly.
```
./src/motionsim.exe -i 10000 -p 256 -g 22 -r 777 -c 0 -o 1
```
2. Clean the project files. (Optional)
```
make clean
```

### On Windows*
1. Run the sample.
### On Windows
1. Specify the input values, and run the program.
```
motionsim.exe 10000 256 22 777 0 1
```
2. Clean the projects files. (Optional)
```
nmake clean
```

### On Linux*
1. Run the sample using default parameters.
```
$ make run
```
2. Alternatively, run the sample using custom parameters shown below.

The following table describes each command line parameter (applies to Linux builds only)

| Flag and Argument | Description | Range of Possible Values | Default
|:--- |:--- |:--- |:---
| `-i num_iterations` | Number of iterations | [1, &#8734;] | 10000
| `-p num_particles` | Number of particles | [1, &#8734;] | 256
| `-g grid_size` | Size of square grid | [1, &#8734;] | 22
| `-r rng_seed` | Random number generator seed | [-&#8734;, &#8734;] | 777
| `-c cpu_flag` | Turns cpu comparison on/off | [1 \| 0] | 0
| `-o output_flag` | Turns grid output on/off | [1 \| 0] | 1
| `-h` | Help message. | |

> **Note**:
>
>- If the grid size specified is greater than **44**, the application will not print the grid even if the grid output flag is on.
>- If a particular parameter is not specified, the application will choose the default value for that parameter.
>- Typing `$ ./src/motionsim.exe -h` displays a brief help message and exits the program.
### Build and Run the `Particle Diffusion` Sample in Intel® DevCloud (Optional)
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.

You can run the program using the above parameters with the application binary:
```
$ ./src/motionsim.exe
```
Example usage:
```
$ ./src/motionsim.exe -i 1000 -p 200 -g 30 -r 777 -c 1 -o 0
qsub -I -l nodes=1:gpu:ppn=2 -d .
```

- `-I` (upper case I) requests an interactive session.
- `-l nodes=1:gpu:ppn=2` (lower case L) assigns one full GPU node.
- `-d .` makes the current folder as the working directory for the task.

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.

For more information on using Intel® DevCloud, see the Intel® oneAPI Base Toolkit [Get Started Guide](https://devcloud.intel.com/oneapi/get_started/).

## Example Output
```
**Running with default parameters**

Running on: Intel(R) Gen9
Device Max Work Group Size: 256
Device Max EUCount: 24
Expand Down Expand Up @@ -240,7 +256,6 @@ $ ./src/motionsim.exe -i 1000 -p 200 -g 30 -r 777 -c 1 -o 0
**********************************************************

Success.
Built target run
```

## License
Expand Down