Main Content

parallel.gpu.enableCUDAForwardCompatibility

Query and set forward compatibility for GPU devices

    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.

    Forward compatibility allows you to use a GPU device with an architecture that was released after your version of MATLAB was built, by recompiling the device libraries at runtime.

    When forward compatibility is enabled, 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 up to an hour. Increase the CUDA cache size to prevent a recurrence of this delay. For instructions, see the end of this section.

    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. You must enable forward compatibility if you want to use this GPU device in MATLAB.

    Caution

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

    The degree of success of recompilation of device libraries can vary depending on the device architecture and the CUDA version used by MATLAB. 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 only limited functionality.

    You can enable forward compatibility for GPU devices using the following methods.

    • Use the function parallel.gpu.enableCUDAForwardCompatibility. Enabling forward compatibility using this method is not persistent between MATLAB sessions.

    • Set the environment variable MW_CUDA_FORWARD_COMPATIBILITY to 1. This can preserve the forward compatibility between MATLAB sessions. If you change the environment variable while MATLAB is running, you must restart MATLAB to see the effect. On the client, you can use setenv to set environment variables. You can then copy environment variables from the client to the workers so that the workers perform computations in the same way as the client. For more information, use Set Environment Variables on Workers.

    Increase the CUDA Cache Size

    • If your GPU architecture does not have built-in binary support in your MATLAB release, the graphics driver must compile and cache the GPU libraries. This process can take up to an hour the first time you access the GPU from MATLAB. To increase the CUDA cache size to prevent a recurrence of this delay, set the environment variable CUDA_CACHE_MAXSIZE to a minimum of 536870912 (512 MB). On the client, you can use setenv to set environment variables. You can then copy environment variables from the client to the workers so that the workers perform computations in the same way as the client. For more information, use Set Environment Variables on Workers.

    Version History

    Introduced in R2020b