0
# Library Management
1
2
Dynamic NVIDIA library loading and discovery utilities for runtime library management and version compatibility. This module provides utilities for discovering, loading, and managing NVIDIA CUDA libraries dynamically at runtime, enabling flexible deployment and version management.
3
4
## Capabilities
5
6
### Dynamic Library Loading
7
8
Load NVIDIA libraries dynamically with automatic discovery and caching.
9
10
```python { .api }
11
def load_nvidia_dynamic_lib(libname: str) -> LoadedDL:
12
"""
13
Load an NVIDIA dynamic library by name with automatic discovery.
14
15
Args:
16
libname (str): Library name (e.g., "cudart", "cublas", "cufft")
17
18
Returns:
19
LoadedDL: Information about the loaded library
20
21
Raises:
22
DynamicLibNotFoundError: If library cannot be found or loaded
23
24
Note:
25
Results are cached for subsequent calls with the same library name
26
"""
27
```
28
29
### Library Discovery
30
31
Discover and locate NVIDIA libraries in the system.
32
33
```python { .api }
34
def find_nvidia_lib_path(libname: str) -> str:
35
"""
36
Find the full path to an NVIDIA library.
37
38
Args:
39
libname (str): Library name to locate
40
41
Returns:
42
str: Absolute path to the library file
43
44
Raises:
45
DynamicLibNotFoundError: If library cannot be found
46
"""
47
48
def get_nvidia_lib_directories() -> list:
49
"""
50
Get list of directories searched for NVIDIA libraries.
51
52
Returns:
53
list[str]: List of search directory paths
54
55
Note:
56
Includes system library paths, CUDA toolkit paths, and environment-specific paths
57
"""
58
```
59
60
### Library Information
61
62
Query information about loaded libraries and supported library types.
63
64
```python { .api }
65
def get_supported_libraries() -> tuple:
66
"""
67
Get tuple of all supported NVIDIA library names.
68
69
Returns:
70
tuple[str]: Supported library names
71
72
Note:
73
Includes core CUDA libraries, math libraries, and specialized libraries
74
"""
75
76
def is_library_available(libname: str) -> bool:
77
"""
78
Check if a specific NVIDIA library is available on the system.
79
80
Args:
81
libname (str): Library name to check
82
83
Returns:
84
bool: True if library is available, False otherwise
85
"""
86
87
def get_library_version(libname: str) -> str:
88
"""
89
Get the version of a loaded NVIDIA library.
90
91
Args:
92
libname (str): Library name
93
94
Returns:
95
str: Library version string
96
97
Raises:
98
DynamicLibNotFoundError: If library is not loaded or available
99
"""
100
```
101
102
### CUDA Bindings Utilities
103
104
Utility functions for working with CUDA objects and version information.
105
106
```python { .api }
107
def get_cuda_native_handle(obj) -> int:
108
"""
109
Get the native CUDA handle from a Python CUDA object.
110
111
Args:
112
obj: Python CUDA object (stream, event, etc.)
113
114
Returns:
115
int: Native CUDA handle as integer
116
117
Note:
118
Enables interoperability between different CUDA Python libraries
119
"""
120
121
def get_ptx_ver(ptx: str) -> str:
122
"""
123
Extract PTX ISA version from PTX source code.
124
125
Args:
126
ptx (str): PTX source code string
127
128
Returns:
129
str: PTX ISA version string
130
131
Note:
132
Useful for determining PTX compatibility requirements
133
"""
134
135
def get_minimal_required_cuda_ver_from_ptx_ver(ptx_version: str) -> int:
136
"""
137
Map PTX ISA version to minimum required CUDA driver version.
138
139
Args:
140
ptx_version (str): PTX ISA version string
141
142
Returns:
143
int: Minimum CUDA driver version required
144
145
Note:
146
Helps determine driver compatibility for PTX code
147
"""
148
```
149
150
### Platform Compatibility
151
152
Handle platform-specific library loading and compatibility checks.
153
154
```python { .api }
155
def get_platform_lib_extension() -> str:
156
"""
157
Get the platform-specific library file extension.
158
159
Returns:
160
str: Library extension (".so" on Linux, ".dll" on Windows, ".dylib" on macOS)
161
"""
162
163
def get_platform_lib_prefix() -> str:
164
"""
165
Get the platform-specific library name prefix.
166
167
Returns:
168
str: Library prefix ("lib" on Unix-like systems, "" on Windows)
169
"""
170
171
def resolve_library_name(libname: str) -> str:
172
"""
173
Resolve a library name to the platform-specific filename.
174
175
Args:
176
libname (str): Base library name
177
178
Returns:
179
str: Platform-specific library filename
180
181
Example:
182
"cudart" -> "libcudart.so" (Linux), "cudart64_12.dll" (Windows)
183
"""
184
```
185
186
## Types
187
188
### Loaded Library Information
189
190
```python { .api }
191
class LoadedDL:
192
"""Information about a loaded dynamic library"""
193
194
abs_path: Optional[str]
195
"""
196
Absolute path to the loaded library file.
197
None if library was loaded from memory or path unavailable.
198
"""
199
200
was_already_loaded_from_elsewhere: bool
201
"""
202
True if library was already loaded by another component.
203
False if this call loaded the library for the first time.
204
"""
205
206
_handle_uint: int
207
"""
208
Platform-agnostic library handle as integer pointer.
209
Used internally for library management operations.
210
"""
211
```
212
213
### Exception Classes
214
215
```python { .api }
216
class DynamicLibNotFoundError(Exception):
217
"""
218
Exception raised when an NVIDIA library cannot be found or loaded.
219
220
This exception is raised when:
221
- Library file doesn't exist in search paths
222
- Library file exists but cannot be loaded (missing dependencies, wrong architecture)
223
- Library name is not in the supported libraries list
224
"""
225
226
def __init__(self, libname: str, message: str): ...
227
```
228
229
### Supported Library Names
230
231
```python { .api }
232
SUPPORTED_NVIDIA_LIBNAMES: tuple = (
233
# Core CUDA Libraries
234
"cudart", # CUDA Runtime
235
"nvfatbin", # Fat Binary utilities
236
"nvJitLink", # JIT Linking
237
"nvrtc", # Runtime Compilation
238
"nvvm", # NVVM Compiler
239
240
# Math Libraries
241
"cublas", # Basic Linear Algebra Subprograms
242
"cublasLt", # BLAS-like Linear Algebra
243
"cufft", # Fast Fourier Transform
244
"cufftw", # FFTW-compatible interface
245
"curand", # Random Number Generation
246
"cusolver", # Dense and Sparse Linear Algebra
247
"cusolverMg", # Multi-GPU Linear Algebra
248
"cusparse", # Sparse Matrix Operations
249
250
# NVIDIA Performance Primitives (NPP)
251
"nppc", # NPP Core
252
"nppial", # NPP Image Arithmetic and Logic
253
"nppicc", # NPP Image Color Conversion
254
"nppidei", # NPP Image Data Exchange and Initialization
255
"nppif", # NPP Image Filtering
256
"nppig", # NPP Image Geometry
257
"nppim", # NPP Image Morphological
258
"nppist", # NPP Image Statistics
259
"nppisu", # NPP Image Support
260
"nppitc", # NPP Image Threshold and Compare
261
"npps", # NPP Signal Processing
262
263
# Specialized Libraries
264
"nvblas", # Drop-in BLAS replacement
265
"nvjpeg", # JPEG encode/decode
266
"cufile" # GPU Direct Storage (Linux only)
267
)
268
```
269
270
### Version Information
271
272
```python { .api }
273
__version__: str # cuda.pathfinder version string "1.1.1a0"
274
```
275
276
## Usage Examples
277
278
### Basic Library Loading
279
280
```python
281
from cuda.pathfinder import load_nvidia_dynamic_lib, DynamicLibNotFoundError
282
283
try:
284
# Load CUDA Runtime library
285
cudart_lib = load_nvidia_dynamic_lib("cudart")
286
287
print(f"CUDA Runtime loaded from: {cudart_lib.abs_path}")
288
print(f"Library handle: {cudart_lib._handle_uint}")
289
print(f"Was already loaded: {cudart_lib.was_already_loaded_from_elsewhere}")
290
291
# Load cuBLAS library
292
cublas_lib = load_nvidia_dynamic_lib("cublas")
293
print(f"cuBLAS loaded from: {cublas_lib.abs_path}")
294
295
except DynamicLibNotFoundError as e:
296
print(f"Failed to load library: {e}")
297
```
298
299
### Library Discovery and Availability
300
301
```python
302
from cuda.pathfinder import (
303
get_supported_libraries,
304
is_library_available,
305
find_nvidia_lib_path,
306
DynamicLibNotFoundError
307
)
308
309
# Check all supported libraries
310
supported_libs = get_supported_libraries()
311
print(f"Supported libraries: {len(supported_libs)}")
312
313
available_libs = []
314
unavailable_libs = []
315
316
for libname in supported_libs:
317
if is_library_available(libname):
318
available_libs.append(libname)
319
try:
320
path = find_nvidia_lib_path(libname)
321
print(f"✓ {libname}: {path}")
322
except DynamicLibNotFoundError:
323
print(f"✓ {libname}: available but path not found")
324
else:
325
unavailable_libs.append(libname)
326
print(f"✗ {libname}: not available")
327
328
print(f"\nSummary:")
329
print(f" Available: {len(available_libs)}/{len(supported_libs)}")
330
print(f" Unavailable: {len(unavailable_libs)}")
331
```
332
333
### Conditional Library Loading
334
335
```python
336
from cuda.pathfinder import (
337
load_nvidia_dynamic_lib,
338
is_library_available,
339
DynamicLibNotFoundError
340
)
341
342
class CUDALibraryManager:
343
"""Manages conditional loading of CUDA libraries."""
344
345
def __init__(self):
346
self.loaded_libs = {}
347
self.core_libs = ["cudart", "nvrtc"]
348
self.math_libs = ["cublas", "cufft", "curand"]
349
self.optional_libs = ["cufile", "nvjpeg"]
350
351
def load_core_libraries(self):
352
"""Load essential CUDA libraries."""
353
for libname in self.core_libs:
354
try:
355
lib = load_nvidia_dynamic_lib(libname)
356
self.loaded_libs[libname] = lib
357
print(f"Core library {libname} loaded successfully")
358
except DynamicLibNotFoundError:
359
print(f"ERROR: Core library {libname} not found!")
360
raise
361
362
def load_math_libraries(self):
363
"""Load mathematical computation libraries."""
364
for libname in self.math_libs:
365
try:
366
lib = load_nvidia_dynamic_lib(libname)
367
self.loaded_libs[libname] = lib
368
print(f"Math library {libname} loaded successfully")
369
except DynamicLibNotFoundError:
370
print(f"Warning: Math library {libname} not available")
371
372
def load_optional_libraries(self):
373
"""Load optional/specialized libraries."""
374
for libname in self.optional_libs:
375
if is_library_available(libname):
376
try:
377
lib = load_nvidia_dynamic_lib(libname)
378
self.loaded_libs[libname] = lib
379
print(f"Optional library {libname} loaded successfully")
380
except DynamicLibNotFoundError:
381
print(f"Optional library {libname} failed to load")
382
else:
383
print(f"Optional library {libname} not available on this system")
384
385
def get_loaded_libraries(self):
386
"""Get list of successfully loaded libraries."""
387
return list(self.loaded_libs.keys())
388
389
def has_library(self, libname):
390
"""Check if a specific library is loaded."""
391
return libname in self.loaded_libs
392
393
# Example usage
394
manager = CUDALibraryManager()
395
396
# Load libraries in order of importance
397
try:
398
manager.load_core_libraries()
399
manager.load_math_libraries()
400
manager.load_optional_libraries()
401
402
print(f"\nLoaded libraries: {manager.get_loaded_libraries()}")
403
404
# Check for specific capabilities
405
if manager.has_library("cufft"):
406
print("FFT operations available")
407
408
if manager.has_library("cufile"):
409
print("GPU Direct Storage available")
410
411
if manager.has_library("nvjpeg"):
412
print("Hardware JPEG encoding/decoding available")
413
414
except DynamicLibNotFoundError as e:
415
print(f"Critical library loading failed: {e}")
416
```
417
418
### Platform-Specific Library Handling
419
420
```python
421
from cuda.pathfinder import (
422
get_platform_lib_extension,
423
get_platform_lib_prefix,
424
resolve_library_name,
425
get_nvidia_lib_directories,
426
load_nvidia_dynamic_lib
427
)
428
import platform
429
430
def show_platform_info():
431
"""Display platform-specific library information."""
432
433
print(f"Platform: {platform.system()} {platform.architecture()[0]}")
434
print(f"Library prefix: '{get_platform_lib_prefix()}'")
435
print(f"Library extension: '{get_platform_lib_extension()}'")
436
437
# Show how library names are resolved
438
test_libs = ["cudart", "cublas", "cufft"]
439
print(f"\nLibrary name resolution:")
440
for libname in test_libs:
441
resolved = resolve_library_name(libname)
442
print(f" {libname} -> {resolved}")
443
444
# Show search directories
445
search_dirs = get_nvidia_lib_directories()
446
print(f"\nLibrary search directories:")
447
for i, directory in enumerate(search_dirs):
448
print(f" {i+1}. {directory}")
449
450
def cross_platform_library_loader(libname):
451
"""Cross-platform library loading with detailed information."""
452
453
print(f"Loading {libname}...")
454
455
try:
456
# Show resolved name
457
resolved_name = resolve_library_name(libname)
458
print(f" Resolved name: {resolved_name}")
459
460
# Load library
461
lib = load_nvidia_dynamic_lib(libname)
462
463
print(f" ✓ Successfully loaded")
464
print(f" Path: {lib.abs_path}")
465
print(f" Handle: 0x{lib._handle_uint:x}")
466
467
if lib.was_already_loaded_from_elsewhere:
468
print(f" Note: Library was already loaded by another component")
469
470
return lib
471
472
except Exception as e:
473
print(f" ✗ Failed to load: {e}")
474
return None
475
476
# Example usage
477
show_platform_info()
478
479
print(f"\n" + "="*50)
480
print("Loading test libraries:")
481
482
test_libraries = ["cudart", "cublas", "nvrtc", "cufile"]
483
loaded = {}
484
485
for libname in test_libraries:
486
result = cross_platform_library_loader(libname)
487
if result:
488
loaded[libname] = result
489
print()
490
491
print(f"Successfully loaded {len(loaded)} out of {len(test_libraries)} libraries")
492
```
493
494
### Library Version Management
495
496
```python
497
from cuda.pathfinder import (
498
load_nvidia_dynamic_lib,
499
get_library_version,
500
DynamicLibNotFoundError
501
)
502
import cuda.pathfinder
503
504
def check_library_versions():
505
"""Check versions of loaded NVIDIA libraries."""
506
507
print(f"cuda.pathfinder version: {cuda.pathfinder.__version__}")
508
print(f"\nNVIDIA Library Versions:")
509
510
# Libraries that typically provide version information
511
version_libs = [
512
"cudart", # CUDA Runtime
513
"cublas", # cuBLAS
514
"cufft", # cuFFT
515
"nvrtc", # NVRTC
516
]
517
518
for libname in version_libs:
519
try:
520
# Load library
521
lib = load_nvidia_dynamic_lib(libname)
522
523
# Try to get version (this might not be implemented for all libraries)
524
try:
525
version = get_library_version(libname)
526
print(f" {libname}: {version}")
527
except (NotImplementedError, AttributeError):
528
print(f" {libname}: loaded, version info not available")
529
530
except DynamicLibNotFoundError:
531
print(f" {libname}: not available")
532
533
def version_compatibility_check():
534
"""Check version compatibility between libraries."""
535
536
try:
537
# Load CUDA Runtime
538
cudart = load_nvidia_dynamic_lib("cudart")
539
print(f"CUDA Runtime: {cudart.abs_path}")
540
541
# Load NVRTC (should be compatible with runtime)
542
nvrtc = load_nvidia_dynamic_lib("nvrtc")
543
print(f"NVRTC: {nvrtc.abs_path}")
544
545
# Check if both libraries exist in same directory (common for compatible versions)
546
if cudart.abs_path and nvrtc.abs_path:
547
cudart_dir = cudart.abs_path.rsplit('/', 1)[0]
548
nvrtc_dir = nvrtc.abs_path.rsplit('/', 1)[0]
549
550
if cudart_dir == nvrtc_dir:
551
print("✓ Libraries appear to be from the same CUDA installation")
552
else:
553
print("⚠ Libraries from different directories - version mismatch possible")
554
print(f" CUDA Runtime directory: {cudart_dir}")
555
print(f" NVRTC directory: {nvrtc_dir}")
556
557
except DynamicLibNotFoundError as e:
558
print(f"Version compatibility check failed: {e}")
559
560
# Run version checks
561
check_library_versions()
562
print("\n" + "="*50)
563
version_compatibility_check()
564
```