[paulromano]

Description

The recently added StellaratorSource currently proposes both angles uniformly and rejects against one constant bound for each radial interval. A localized peak therefore increases rejection throughout the interval. The existing bound uses an angular-grid maximum with a 5% margin, which can miss peaks between grid points.

This PR introduces an improved method for the angular sampling by partitioning one field period into 32x32 angular cells and constructing a radius-dependent bound for each cell. It samples cells in proportion to their bounds, proposes angles uniformly inside the selected cell, and accepts by rejection sampling. A runtime check detects invalid densities and encountered bound violations.

Additionally, I've put together a new "Source Sampling" section of our Theory and Methodology documentation which goes through the derivation of the radial and angular algorithms for StellaratorSource and also includes all of our other source classes.

Testing Results

I carried out some measurements using the W7-X, HSX, and NCSX examples bundled with DESC (desc.examples.get(name)), which have 288, 179, and 196 retained Fourier modes, respectively. Each uses the analytic benchmark emission profile $S(\rho)=(1-\rho^2)^2$. Measurements used a single thread on an Intel Core Ultra 7 258V and sampling 500,000 source site via openmc_sample_external_source. Based on the results below, you can see that throughput improves by 17–26%, with 0.09–0.47 s of additional initialization in these runs.

Example	Surfaces	develop sites/s	PR sites/s	Average speedup	develop init, s	PR init, s
W7-X	33	67,600	83,400	1.23×	0.532	0.776
W7-X	101	77,200	90,800	1.18×	1.218	1.693
HSX	33	102,400	119,400	1.17×	0.353	0.467
HSX	101	105,400	128,200	1.22×	0.445	0.583
NCSX	33	87,700	110,500	1.26×	0.350	0.441
NCSX	101	96,200	115,800	1.20×	0.479	0.935

The additional memory requirements are approximately 72 KiB per radial interval: 2.25 MiB at 33 surfaces and 7.03 MiB at 101 surfaces, plus small bookkeeping overhead.

AI Assistance

• Harness: Codex
• Model: GPT-6-Astra; GPT-6.1-Sol
• Reasoning effort: medium (GPT-6-Astra); high (GPT-6.1-Sol)

Checklist

• I have performed a self-review of my own code
• I have run clang-format (version 18) on any C++ source files (if applicable)
• I have followed the style guidelines for Python source files (if applicable)
• I have made corresponding changes to the documentation (if applicable)
• I have added tests that prove my fix is effective or that my feature works (if applicable)

Summary by CodeRabbit

• Improvements
  • Updated stellarator source sampling to select points using angular regions and density-based acceptance, with support for different field-period counts and vertical orientations.
• Documentation
  • Added guidance on source-site fields and sampling across source types, including stellarator and tokamak geometries, constraints, and biasing.

[coderabbitai]

No actionable comments were generated in the recent review.

Recent review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 4ae2334b-47db-46d2-b83e-0660573f3493

Commits

Reviewing files that changed from the base of the PR and between c630113 and 17765c1.

Files selected for processing: 6

• docs/source/methods/index.rst
• docs/source/methods/source_sampling.rst
• include/openmc/source.h
• openmc/source.py
• src/source.cpp
• tests/unit_tests/test_source_stellarator.py

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 3 remain after this review.

Walkthrough

The stellarator source sampler now selects angular cells using radial Bernstein components and precomputed bounds. Sampling documentation and tests were also added.

Changes: Stellarator Source Sampling

Layer / File(s)	Summary
Angular bounds and distributions include/openmc/source.h, src/source.cpp	The sampler computes positive and negative density bounds for angular cells and uses the radial Bernstein controls to build cell-selection distributions. The previous scalar envelope setup is removed.
Cell sampling and validation include/openmc/source.h, src/source.cpp, openmc/source.py, tests/unit_tests/test_source_stellarator.py	At a sampled radius, the sampler selects a Bernstein component and angular cell, proposes angles within that cell, and checks density against the cell bound. It then selects a field period uniformly. The tests check tube containment and analytic sample moments across field-period counts and orientations.
Source sampling documentation docs/source/methods/index.rst, docs/source/methods/source_sampling.rst	The methods documentation now includes a source sampling page covering source types, distributions, sampling procedures, constraints, and biasing.

Priority: Normal

Estimated code review effort: 4 (Complex) | ~40 minutes

Change: Bug fix

Merge Risk: Minimal · up to 17765

No issue requiring a fix before merge was identified.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 4 files. (2 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title clearly and concisely identifies the main change: improving stellarator angular sampling with radius-dependent cell bounds.
Description check		The description explains the motivation, implementation, performance results, memory impact, AI assistance, testing, documentation changes, and completed checklist items. No issue number is provided, …
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description explains the motivation, implementation, performance results, memory impact, AI assistance, testing, documentation changes, and completed checklist items. No issue number is provided, but the template marks issue linkage as applicable only when relevant.

Full details: Docstring Coverage

Explanation

Docstring coverage is 54.55% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 11 functions across 4 files. (2 skipped: 2 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}