Main Content

parallel.gpu.enableCUDAForwardCompatibility

Query and set forward compatibility for GPU devices

Since R2020b

collapse all in page

    Syntax

    tf = parallel.gpu.enableCUDAForwardCompatibility()
    parallel.gpu.enableCUDAForwardCompatibility(tf)

    Description

    tf = parallel.gpu.enableCUDAForwardCompatibility() returns true if forward compatibility for GPU devices is enabled and false otherwise. The default is false.

    When forward compatibility is disabled, you cannot perform computations using a GPU device with an architecture that was released after the version of MATLAB® you are using was built.

    parallel.gpu.enableCUDAForwardCompatibility(tf) enables or disables forward compatibility for GPU devices. tf must be true (1) or false (0).

    If you enable forward compatibility, the CUDA® driver recompiles the GPU libraries the first time you access a device with an architecture newer than your MATLAB version. Recompilation can take several minutes.

    Enabling forward compatibility is not persistent between MATLAB sessions.

    Caution

    Enabling forward compatibility can result in wrong answers and unexpected behavior during GPU computations.

    For more information, see Forward Compatibility for GPU Devices.

    Examples

    collapse all

    If you have a GPU with an architecture that was released after the version of MATLAB you are using, by default, you cannot use that GPU to perform computations in MATLAB. To use that GPU in MATLAB, enable forward compatibility for GPU devices.

    Check whether forward compatibility is enabled.

    tf = parallel.gpu.enableCUDAForwardCompatibility()
    tf = 
   0

    Enable forward compatibility.

    parallel.gpu.enableCUDAForwardCompatibility(1)

    Select and use the GPU device. 

    gpuDevice(2);
A = ones(100,'gpuArray');

    The first time you access the GPU from MATLAB, the CUDA driver recompiles the libraries. Recompilation can take several minutes.

    Input Arguments

    collapse all

    Forward compatibility status to set, specified as a numeric or logical 1 (true) or 0 (false).

    Example: 0

    Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

    Forward Compatibility for GPU Devices

    Note

    Starting in R2020b, forward compatibility for GPU devices is disabled by default.

    In R2020a and earlier releases, you cannot disable forward compatibility for GPU devices.

    Enable forward compatibility to use a GPU device with an architecture that was released after your version of MATLAB.

    When you enable forward compatibility, the CUDA driver recompiles the GPU libraries the first time you access a device with an architecture newer than your MATLAB version. Recompilation takes up to an hour. To prevent a recurrence of this delay, increase the CUDA cache size. For instructions on how to increase the CUDA cache size, see Increase the CUDA Cache Size.

    Caution

    Enabling forward compatibility can result in wrong answers and unexpected behavior during GPU computations.

    The degree of success of recompilation of device libraries varies depending on the device architecture and the CUDA that MATLAB uses. In some cases, forward compatibility does not work as expected and recompilation of the libraries results in errors.

    For example, forward compatibility from CUDA version 10.0–10.2 (MATLAB versions R2019a, R2019b, R2020a, and R2020b) to Ampere (compute capability 8.x) has limited functionality.

    Enable Forward Compatibility for GPU Devices

    You can enable forward compatibility for GPU devices using either of these methods.

    • Use the parallel.gpu.enableCUDAForwardCompatibility function. When you use this function, forward compatibility does not persistent between MATLAB sessions. To automatically enable forward compatibility when MATLAB starts, call the parallel.gpu.enableCUDAForwardCompatibility function in a startup script.

    • Set the MW_CUDA_FORWARD_COMPATIBILITY environment variable to 1. This setting preserves forward compatibility between MATLAB sessions. If you change the environment variable while MATLAB is running, you must restart MATLAB to see the effect.

    Increase the CUDA Cache Size

    To increase the CUDA cache size, set the CUDA_CACHE_MAXSIZE environment variable to a minimum of 536870912 (512 MB).

    Set Environment Variables

    To set environment variables on the MATLAB client, use the setenv function. If you are using parallel workers, see Set Environment Variables on Workers.

    Extended Capabilities

    Version History

    Introduced in R2020b

    See Also

    | |

    Topics