The Occupancy Calculator API
cudaOccupancyMaxPotentialBlockSize.
The Occupancy Calculator API is a free CUDA Academy lesson on CoddyKit — lesson 3 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the CUDA Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Stop Guessing Block Size
Instead of hand-tuning, CUDA offers an occupancy API that computes a good block size for your kernel automatically.
The Star Function
One call does the heavy lifting: cudaOccupancyMaxPotentialBlockSize suggests a block size that maximizes occupancy.
cudaOccupancyMaxPotentialBlockSize(&grid, &block, myKernel);What It Returns
It fills in a suggested block size and the minimum grid size needed to fully occupy the device for your kernel.
It Knows Your Kernel
The API reads your kernels real register and shared memory use, so its suggestion fits that exact kernel, not a generic guess.
Predicting Occupancy
A sibling call reports how many active blocks per SM a config gives, so you can predict occupancy before launching.
cudaOccupancyMaxActiveBlocksPerMultiprocessor(&n, k, 256, 0);Computing the Percentage
Multiply blocks per SM by warps per block, divide by the SM warp max, and you get the theoretical occupancy percentage.
Dynamic Shared Memory
These calls take a dynamic shared memory argument, so the prediction stays accurate when your kernel sizes shared memory at launch.
Portable Across GPUs
Because it queries the running device, the same code picks good sizes on different GPUs without you hardcoding numbers.
Use It at Startup
Call the occupancy API once during initialization, cache the block size, then reuse it for every launch of that kernel.
A Strong Default
The suggested size is an excellent starting point. You can still benchmark a few neighbors to find the true best for your data.
Why It Beats Magic Numbers
Hardcoded sizes like 256 break when resources change. The API adapts, keeping your kernel near peak occupancy automatically.
Quick Check
Recall what cudaOccupancyMaxPotentialBlockSize gives you.
Recap
You met the occupancy API: it suggests a portable, kernel-aware block size and predicts occupancy before you ever launch. ⚙️
Frequently asked questions
Is the “The Occupancy Calculator API” lesson free?
Yes — the full text of “The Occupancy Calculator API” is free to read here on the web, and the CUDA Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the CUDA Academy course, upgrade to CoddyKit PRO.
What will I learn in “The Occupancy Calculator API”?
cudaOccupancyMaxPotentialBlockSize. You practise CUDA Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start CUDA Academy?
No prior experience is required. CUDA Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “The Occupancy Calculator API” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this CUDA Academy lesson?
Yes. Every CUDA Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- What Occupancy Really Means
- Registers and Shared Memory Limits
- The Occupancy Calculator API
- Occupancy Is Not the Whole Story