mirror of
https://github.com/andreinechaev/nvcc4jupyter.git
synced 2026-06-14 03:00:47 +05:30
Cosmin Ștefan Ciocan
781ff5b76b
* Add option to give nvcc extra arguments * Add test for nvcc options that changes c++ dialect from c++17 to c++14 * Add make and the english language pack to devcontainer to be able to build the documentation * Update documentation config to automatically import the current version of the package * Document new --compiler-args argument * Improve tests coverage by testing for bad arguments and the error output during a failed compilation * Add IPython to docs requirements to allow the __version__ import for readthedocs env * Change devcontainer base image to have the latest CUDA toolkit * Mock the nsight compute tool with a bash script * Add test to compile with opencv * Add new page to documentation that contains a new notebook that explains compiling with external libraries * Add autodocstring vscode extension to devcontainer * Add function that modifies the default profiler/compiler arguments to allow reusing them in multiple magic command calls * Update pylint exceptions * Update contributing instructions * Change version from 1.0.3 to 1.1.0 due to adding features in a backward-compatible manner * Install latest CUDA toolkit on the test runner to pass the OpenCV compilation test * Install opencv in test runner and update code coverage install * Add CUDA bin to PATH in test and coverage runners * Add cuda bin to path variable in .bashrc * Update way to set environment variable PATH in github action * Change devcontainer base image back to ubuntu:22.04 to match the environment from the test runner
190 lines
4.6 KiB
ReStructuredText
190 lines
4.6 KiB
ReStructuredText
**********
|
|
Magics API
|
|
**********
|
|
|
|
.. note::
|
|
Arguments for profilers and the nvcc compiler can be passed in double
|
|
quotes so they can contain spaces and dashes.
|
|
|
|
------
|
|
|
|
.. _cuda_magic:
|
|
|
|
cuda
|
|
====
|
|
|
|
Magic command that compiles, runs, and profiles CUDA C++ code in the cell.
|
|
|
|
Usage
|
|
-----
|
|
|
|
- ``%%cuda``: Compile and run this cell.
|
|
- ``%%cuda -p``: Also runs the Nsight Compute profiler.
|
|
- ``%%cuda -p -a "<SPACE SEPARATED PROFILER ARGS>"``: Also runs the Nsight Compute profiler.
|
|
- ``%%cude -c "<SPACE SEPARATED COMPILER ARGS"``: Passes additional arguments to "nvcc".
|
|
- ``%%cuda -t``: Outputs the "timeit" built-in magic results.
|
|
|
|
Options
|
|
-------
|
|
|
|
.. _timeit:
|
|
|
|
-t, --timeit
|
|
Boolean. If set, returns the output of the "timeit" built-in
|
|
ipython magic instead of stdout.
|
|
|
|
.. _profile:
|
|
|
|
-p, --profile
|
|
Boolean. If set, runs the NVIDIA Nsight Compute profiler whose
|
|
output is appended to standard output.
|
|
|
|
.. _profiler_args:
|
|
|
|
-a, --profiler-args
|
|
String. Optional profiler arguments that can be space separated
|
|
by wrapping them in double quotes. See all options here:
|
|
`Nsight Compute CLI <https://docs.nvidia.com/nsight-compute/NsightComputeCli/index.html#command-line-options>`_
|
|
|
|
.. _compiler_args:
|
|
|
|
-c, --compiler-args
|
|
String. Optional compiler arguments that can be space separated
|
|
by wrapping them in double quotes. They will be passed to "nvcc".
|
|
See all options here:
|
|
`NVCC Options <https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/index.html#nvcc-command-options>`_
|
|
|
|
|
|
.. note::
|
|
If both "\-\-profile" and "\-\-timeit" are used then no profiling is
|
|
done.
|
|
|
|
Examples
|
|
--------
|
|
::
|
|
|
|
# compile, run, and profile the code in the cell with the Nsight compute
|
|
# profiler while collecting only metrics from the "MemoryWorkloadAnalysis"
|
|
# section; also provides the "--optimize 3" option to "nvcc" during
|
|
# compilation to optimize host code
|
|
%%cuda -p -a "--section MemoryWorkloadAnalysis" -c "--optimize 3"
|
|
|
|
------
|
|
|
|
.. _cuda_group_save_magic:
|
|
|
|
cuda_group_save
|
|
===============
|
|
|
|
Magic command that saves CUDA C++ code in the cell for later
|
|
compilation and execution with possibly more source files.
|
|
|
|
Usage
|
|
-----
|
|
|
|
- ``%%cuda_group_save -n <FILENAME> -g <GROUPNAME>``: Save the code in the current cell to a group of source files.
|
|
|
|
Options
|
|
-------
|
|
|
|
-n, --name
|
|
String. Required file name of the saved source file. Must have
|
|
either the ".cu" or ".h" extension. In order to import a header
|
|
file saved with this magic you can simply add '#include "<name>"'.
|
|
|
|
-g, --group
|
|
String. Required group name to which to add the saved source file.
|
|
Groups are source files that get compiled together and do not
|
|
interact with other groups. This allows you to have multiple
|
|
unrelated CUDA programs within the same jupyter notebook. Adding
|
|
files to a group named "shared" will make them available to all
|
|
other source file groups. One use case for the shared group is for
|
|
sharing error handling code which should be present in all CUDA
|
|
programs.
|
|
|
|
Examples
|
|
--------
|
|
::
|
|
|
|
# jupyter cell 1
|
|
%%cuda_group_save -n "error_handling.h" -g "shared"
|
|
<ERROR HANDLING CODE>
|
|
|
|
# jupyter cell 2
|
|
%%cuda_group_save -n "main.cu" -g "example_group"
|
|
#include "error_handling.h"
|
|
<YOUR CODE HERE>
|
|
|
|
------
|
|
|
|
.. _cuda_group_run_magic:
|
|
|
|
cuda_group_run
|
|
==============
|
|
|
|
Line magic command that compiles, runs, and profiles all source files
|
|
in a group.
|
|
|
|
Usage
|
|
-----
|
|
|
|
- ``%%cuda_group_run -g <GROUPNAME>``: Compiles, runs, and profiles the sources files in the given group.
|
|
|
|
Options
|
|
-------
|
|
|
|
-g, --group
|
|
String. Required group name whose source files should be deleted.
|
|
|
|
.. note::
|
|
All options from the "%%cuda" cell magic are inherited.
|
|
|
|
Examples
|
|
--------
|
|
::
|
|
|
|
# jupyter cell 1
|
|
%%cuda_group_save -n "error_handling.h" -g "shared"
|
|
<ERROR HANDLING CODE>
|
|
|
|
# jupyter cell 2
|
|
%%cuda_group_save -n "main.cu" -g "example_group"
|
|
#include "error_handling.h"
|
|
<YOUR CODE HERE>
|
|
|
|
# jupyter cell 3
|
|
%cuda_group_run -g "example_group" --profile
|
|
|
|
-----
|
|
|
|
.. _cuda_group_delete_magic:
|
|
|
|
cuda_group_delete
|
|
=================
|
|
|
|
Line magic command that deletes all source files in a group.
|
|
|
|
Usage
|
|
-----
|
|
|
|
- ``%%cuda_group_delete -g <GROUPNAME>``: Removes all source files in the given group.
|
|
|
|
Options
|
|
-------
|
|
|
|
-g, --group
|
|
String. Required group name whose source files should be deleted.
|
|
|
|
Examples
|
|
--------
|
|
::
|
|
|
|
# jupyter cell 1
|
|
%%cuda_group_save -n "error_handling.h" -g "shared"
|
|
<ERROR HANDLING CODE>
|
|
|
|
# jupyter cell 2 - here we delete the error shared group; in
|
|
# practice this would be helpful if you want to overwrite some
|
|
# functionality that was defined earlier in the notebook
|
|
%cuda_group_delete -g "shared"
|