Summary

The OrbitalLocalizer abstraction includes both spatial localization methods and other orbital transformations, notably qdk_natural_orbitals. Some public documentation currently describes the entire abstraction as though every implementation produces spatially localized orbitals.

This came up during an AI review of the code documentation. @wavefunction91, please close this issue if the AI assessment is wrong or if the current terminology is intentional.

Examples of the mismatch

• The Python OrbitalLocalizer base-class docstring says it transforms canonical orbitals into orbitals that are spatially confined to regions or bonds.
• The Python run() docstring says it localizes the input and returns a localized wavefunction.
• The C++ Localizer base-class documentation similarly defines the abstraction only in terms of spatial localization.
• The comprehensive localizer page initially acknowledges “localized or otherwise transformed” orbitals, but later sections and input/output descriptions revert to localization-only wording.
• The concrete natural-orbital documentation correctly describes qdk_natural_orbitals as a transformation that diagonalizes the active-space 1-RDM, not as spatial localization.
• The Python base-class docstring says custom implementations should implement a localize method, while the extension point shown in the example is _run_impl.

Suggested scope

This appears to require documentation clarification only, not a public API rename:

• Describe the abstraction as supporting orbital localization and other orbital transformations.
• Use neutral terms such as “selected orbitals,” “transformed orbitals,” and “output wavefunction” in base-class and run() documentation.
• Reserve “localized” for implementations that actually optimize spatial/local population criteria, such as Pipek–Mezey.
• Clarify that natural orbitals are eigenvectors of an RDM and are not necessarily spatially localized.
• Correct the custom-implementation guidance to name _run_impl rather than localize.
• Align the C++ API, Python API, and comprehensive user documentation.

Acceptance criteria

• Base documentation accurately covers both spatial localizers and natural-orbital transformations.
• Concrete implementation documentation retains method-specific terminology.
• The documented Python subclass extension point matches the actual API.
• No public class, factory type, or factory key is renamed as part of this documentation-only issue.