-
Notifications
You must be signed in to change notification settings - Fork 154
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.
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
Publish Developer Guide #673
Merged
rapids-bot
merged 23 commits into
rapidsai:branch-22.10
from
harrism:fea-publish-developer-guide
Sep 30, 2022
Merged
Changes from 18 commits
Commits
Show all changes
23 commits
Select commit
Hold shift + click to select a range
8dc1ecb
Add DOCUMENTATION.md
harrism 03eeb9d
Add testing.md
harrism f003154
Simplify
harrism 994d401
Add BENCHMARKING.md
harrism 5f7236d
Move developer guide docs
harrism f1666e0
rename refactoring guide.
harrism 814beef
Add layout that links to developer guide.
harrism 84bfaa0
Remove code font from headers
harrism dfc93ec
Missed one.
harrism 36f0105
Merge branch 'fea-documentation-md' into fea-publish-developer-guide
harrism a1b379d
Move documentation and escape @ commands.
harrism d354e01
Remove <a> links
harrism 97bcfa2
Add REFACTORING_GUIDE
harrism a22769f
Add sed command to update tagfile versions in Doxyfile.
harrism 66ee41f
Apply suggestions from code review
harrism 93c1eea
Fix update_version.sh
harrism 9a48170
Link to groups.
harrism 79a8abb
Merge branch 'fea-publish-developer-guide' of github.com:harrism/cusp…
harrism 85b611e
Fix PROJECT_NUMBER update in update_version.sh
harrism 994b8a5
Merge branch 'branch-22.10' into fea-publish-developer-guide
harrism f6434b8
Copy changes made to old files, and delete old files.
harrism cace8e9
cudf --> cuspatial
harrism e8a8912
Improve main_page.md with description and links.
harrism File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,195 @@ | ||
| <doxygenlayout version="1.0"> | ||
| <!-- Generated by doxygen 1.8.13 --> | ||
| <!-- Navigation index tabs for HTML output --> | ||
| <navindex> | ||
| <tab type="mainpage" visible="yes" title=""/> | ||
| <tab type="pages" visible="yes" title="" intro=""/> | ||
| <tab type="user" url="@ref DEVELOPER_GUIDE" title="Developer Guide"/> | ||
| <tab type="modules" visible="yes" title="" intro=""/> | ||
| <tab type="namespaces" visible="yes" title=""> | ||
| <tab type="namespacelist" visible="yes" title="" intro=""/> | ||
| <tab type="namespacemembers" visible="yes" title="" intro=""/> | ||
| </tab> | ||
| <tab type="classes" visible="yes" title=""> | ||
| <tab type="classlist" visible="yes" title="" intro=""/> | ||
| <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/> | ||
| <tab type="hierarchy" visible="yes" title="" intro=""/> | ||
| <tab type="classmembers" visible="yes" title="" intro=""/> | ||
| </tab> | ||
| <tab type="files" visible="yes" title=""> | ||
| <tab type="filelist" visible="yes" title="" intro=""/> | ||
| <tab type="globals" visible="yes" title="" intro=""/> | ||
| </tab> | ||
| <tab type="examples" visible="yes" title="" intro=""/> | ||
| </navindex> | ||
|
|
||
| <!-- Layout definition for a class page --> | ||
| <class> | ||
| <briefdescription visible="yes"/> | ||
| <includes visible="$SHOW_INCLUDE_FILES"/> | ||
| <inheritancegraph visible="$CLASS_GRAPH"/> | ||
| <collaborationgraph visible="$COLLABORATION_GRAPH"/> | ||
| <memberdecl> | ||
| <nestedclasses visible="yes" title=""/> | ||
| <publictypes title=""/> | ||
| <services title=""/> | ||
| <interfaces title=""/> | ||
| <publicslots title=""/> | ||
| <signals title=""/> | ||
| <publicmethods title=""/> | ||
| <publicstaticmethods title=""/> | ||
| <publicattributes title=""/> | ||
| <publicstaticattributes title=""/> | ||
| <protectedtypes title=""/> | ||
| <protectedslots title=""/> | ||
| <protectedmethods title=""/> | ||
| <protectedstaticmethods title=""/> | ||
| <protectedattributes title=""/> | ||
| <protectedstaticattributes title=""/> | ||
| <packagetypes title=""/> | ||
| <packagemethods title=""/> | ||
| <packagestaticmethods title=""/> | ||
| <packageattributes title=""/> | ||
| <packagestaticattributes title=""/> | ||
| <properties title=""/> | ||
| <events title=""/> | ||
| <privatetypes title=""/> | ||
| <privateslots title=""/> | ||
| <privatemethods title=""/> | ||
| <privatestaticmethods title=""/> | ||
| <privateattributes title=""/> | ||
| <privatestaticattributes title=""/> | ||
| <friends title=""/> | ||
| <related title="" subtitle=""/> | ||
| <membergroups visible="yes"/> | ||
| </memberdecl> | ||
| <detaileddescription title=""/> | ||
| <memberdef> | ||
| <inlineclasses title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <services title=""/> | ||
| <interfaces title=""/> | ||
| <constructors title=""/> | ||
| <functions title=""/> | ||
| <related title=""/> | ||
| <variables title=""/> | ||
| <properties title=""/> | ||
| <events title=""/> | ||
| </memberdef> | ||
| <allmemberslink visible="yes"/> | ||
| <usedfiles visible="$SHOW_USED_FILES"/> | ||
| <authorsection visible="yes"/> | ||
| </class> | ||
|
|
||
| <!-- Layout definition for a namespace page --> | ||
| <namespace> | ||
| <briefdescription visible="yes"/> | ||
| <memberdecl> | ||
| <nestednamespaces visible="yes" title=""/> | ||
| <constantgroups visible="yes" title=""/> | ||
| <classes visible="yes" title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <functions title=""/> | ||
| <variables title=""/> | ||
| <membergroups visible="yes"/> | ||
| </memberdecl> | ||
| <detaileddescription title=""/> | ||
| <memberdef> | ||
| <inlineclasses title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <functions title=""/> | ||
| <variables title=""/> | ||
| </memberdef> | ||
| <authorsection visible="yes"/> | ||
| </namespace> | ||
|
|
||
| <!-- Layout definition for a file page --> | ||
| <file> | ||
| <briefdescription visible="yes"/> | ||
| <includes visible="$SHOW_INCLUDE_FILES"/> | ||
| <includegraph visible="$INCLUDE_GRAPH"/> | ||
| <includedbygraph visible="$INCLUDED_BY_GRAPH"/> | ||
| <sourcelink visible="yes"/> | ||
| <memberdecl> | ||
| <classes visible="yes" title=""/> | ||
| <namespaces visible="yes" title=""/> | ||
| <constantgroups visible="yes" title=""/> | ||
| <defines title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <functions title=""/> | ||
| <variables title=""/> | ||
| <membergroups visible="yes"/> | ||
| </memberdecl> | ||
| <detaileddescription title=""/> | ||
| <memberdef> | ||
| <inlineclasses title=""/> | ||
| <defines title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <functions title=""/> | ||
| <variables title=""/> | ||
| </memberdef> | ||
| <authorsection/> | ||
| </file> | ||
|
|
||
| <!-- Layout definition for a group page --> | ||
| <group> | ||
| <briefdescription visible="yes"/> | ||
| <groupgraph visible="$GROUP_GRAPHS"/> | ||
| <memberdecl> | ||
| <nestedgroups visible="yes" title=""/> | ||
| <dirs visible="yes" title=""/> | ||
| <files visible="yes" title=""/> | ||
| <namespaces visible="yes" title=""/> | ||
| <classes visible="yes" title=""/> | ||
| <defines title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <enumvalues title=""/> | ||
| <functions title=""/> | ||
| <variables title=""/> | ||
| <signals title=""/> | ||
| <publicslots title=""/> | ||
| <protectedslots title=""/> | ||
| <privateslots title=""/> | ||
| <events title=""/> | ||
| <properties title=""/> | ||
| <friends title=""/> | ||
| <membergroups visible="yes"/> | ||
| </memberdecl> | ||
| <detaileddescription title=""/> | ||
| <memberdef> | ||
| <pagedocs/> | ||
| <inlineclasses title=""/> | ||
| <defines title=""/> | ||
| <typedefs title=""/> | ||
| <enums title=""/> | ||
| <enumvalues title=""/> | ||
| <functions title=""/> | ||
| <variables title=""/> | ||
| <signals title=""/> | ||
| <publicslots title=""/> | ||
| <protectedslots title=""/> | ||
| <privateslots title=""/> | ||
| <events title=""/> | ||
| <properties title=""/> | ||
| <friends title=""/> | ||
| </memberdef> | ||
| <authorsection visible="yes"/> | ||
| </group> | ||
|
|
||
| <!-- Layout definition for a directory page --> | ||
| <directory> | ||
| <briefdescription visible="yes"/> | ||
| <directorygraph visible="yes"/> | ||
| <memberdecl> | ||
| <dirs visible="yes"/> | ||
| <files visible="yes"/> | ||
| </memberdecl> | ||
| <detaileddescription title=""/> | ||
| </directory> | ||
| </doxygenlayout> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # Unit Benchmarking in libcuspatial | ||
|
|
||
| Unit benchmarks in libcuspatial are written using [NVBench](https://github.com/NVIDIA/nvbench). | ||
| While some existing benchmarks are written using | ||
| [Google Benchmark](https://github.com/google/benchmark), new benchmarks should use NVBench. | ||
|
|
||
| The NVBench library is similar to Google Benchmark, but has several quality of life improvements | ||
| when doing GPU benchmarking such as displaying the fraction of peak memory bandwidth achieved and | ||
| details about the GPU hardware. | ||
|
|
||
| Both NVBench and Google Benchmark provide many options for specifying ranges of parameters to | ||
| benchmark, as well as to control the time unit reported, among other options. Refer to existing | ||
| benchmarks in `cpp/benchmarks` to understand the options. | ||
|
|
||
| ## Directory and File Naming | ||
|
|
||
| The naming of unit benchmark directories and source files should be consistent with the feature | ||
| being benchmarked. For example, the benchmarks for APIs in `point_in_polygon.hpp` should live in | ||
| `cpp/benchmarks/point_in_polygon.cu`. Each feature (or set of related features) should have its own | ||
| benchmark source file named `<feature>{.cu,cpp}`. | ||
|
|
||
| In the interest of improving compile time, whenever possible, test source files should be `.cpp` | ||
| files because `nvcc` is slower than `gcc` in compiling host code. Note that `thrust::device_vector` | ||
| includes device code, and so must only be used in `.cu` files. `rmm::device_uvector`, | ||
| `rmm::device_buffer` and the various `column_wrapper` types described in [Testing](TESTING.md) | ||
| can be used in `.cpp` files, and are therefore preferred in test code over `thrust::device_vector`. | ||
|
|
||
| Testing header-only APIs requires CUDA compilation so should be done in `.cu` files. | ||
|
|
||
| ## CUDA Asynchrony and benchmark accuracy | ||
|
|
||
| CUDA computations and operations like copies are typically asynchronous with respect to host code, | ||
| so it is important to carefully synchronize in order to ensure the benchmark timing is not stopped | ||
| before the feature you are benchmarking has completed. An RAII helper class `cuda_event_timer` is | ||
| provided in `cpp/benchmarks/synchronization/synchronization.hpp` to help with this. This class | ||
| can also optionally clear the GPU L2 cache in order to ensure cache hits do not artificially inflate | ||
| performance in repeated iterations. | ||
|
|
||
| ## Data generation | ||
|
|
||
| For generating benchmark input data, random data generation functions are provided in | ||
| `cpp/benchmarks/utility/random.cuh`. The input data generation happens on device. | ||
|
|
||
| ## What should we benchmark? | ||
|
|
||
| In general, we should benchmark all features over a range of data sizes and types, so that we can | ||
| catch regressions across libcudf changes. However, running many benchmarks is expensive, so ideally | ||
| we should sample the parameter space in such a way to get good coverage without having to test | ||
| exhaustively. | ||
|
|
||
| A rule of thumb is that we should benchmark with enough data to reach the point where the algorithm | ||
| reaches its saturation bottleneck, whether that bottleneck is bandwidth or computation. Using data | ||
| sets larger than this point is generally not helpful, except in specific cases where doing so | ||
| exercises different code and can therefore uncover regressions that smaller benchmarks will not | ||
| (this should be rare). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One more update needed here. You can test this with various version numbers to ensure that everything works as intended. For example, run the following and check the
diffeach time.