fix(postprocess): normalize unified eigen solver options

[QG-phy]

This PR extracts the still-useful part of #325 into a smaller change based on the current main branch.

Fixes #324.

Summary

• Accept eig_solver as a compatibility alias in unified TBSystem APIs.
• Keep solver as the preferred unified API name.
• Raise ValueError if both solver and eig_solver are provided with different values.
• Forward nk through unified band and DOS eigenvalue calculations so users can control k-point chunking.
• Recompute cached band and DOS results when result-sensitive inputs change instead of returning stale cached data.
• Keep nk out of cache invalidation because it only controls k-point chunking and does not change the sampled k-points or numerical result.

Notes

The legacy APIs and run configs still use eig_solver; the unified TBSystem layer now accepts it for migration compatibility and normalizes it internally to solver before calling the lower-level eigenvalue code.

This intentionally does not include the override_overlap changes from #325. Current main already has per-call override_overlap support with newer overlap/eigensolver handling, while #325's instance-level default/opt-out approach adds extra state semantics and should not be carried into this focused fix.

Validation

• python -m py_compile dptb/postprocess/unified/system.py dptb/postprocess/unified/properties/band.py dptb/postprocess/unified/properties/dos.py dptb/tests/test_postprocess_unified.py
• uv run pytest dptb/tests/test_postprocess_unified.py -q
• uv run pytest dptb/tests/test_band.py -q

[coderabbitai]

Warning

Rate limit exceeded

@QG-phy has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 51 minutes and 35 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4231aadc-cacc-49b6-953e-2900cb732498

📥 Commits

Reviewing files that changed from the base of the PR and between 0c74396 and 2a04f12.

📒 Files selected for processing (3)

• dptb/postprocess/unified/properties/dos.py
• dptb/postprocess/unified/system.py
• dptb/tests/test_postprocess_unified.py

📝 Walkthrough

Walkthrough

This PR extends the eigenvalue solver interface to accept configuration parameters beyond atomic data, implements centralized solver kwargs extraction with alias support in TBSystem, and adds intelligent caching to avoid recomputation when only transient parameters like nk change while preserving recomputation when configuration changes.

Changes

Solver kwargs and eigenvalue parameter support throughout postprocessing stack

Layer / File(s)	Summary
Abstract calculator API updates dptb/postprocess/unified/calculator.py	HamiltonianCalculator.get_eigenvalues and get_eigenstates abstract methods now accept **kwargs to enable solver implementations to support variable configuration options.
Property accessors accept and forward solver parameters dptb/postprocess/unified/properties/band.py, dptb/postprocess/unified/properties/dos.py	BandAccessor.compute and DosAccessor.compute gain optional nk parameter and forward it to calculator eigenvalue/eigenstate calls. DosAccessor warns that solver and ill_threshold are ignored in PDOS paths.
TBSystem solver kwargs extraction and caching helpers dptb/postprocess/unified/system.py	New helper methods extract and validate solver-related kwargs with solver/eig_solver alias support, normalize values for deterministic cache keys, compare cache keys for reuse decisions, and build band and DOS-specific cache keys from solver and configuration parameters.
TBSystem method refactoring for centralized caching dptb/postprocess/unified/system.py	get_efermi, get_bands, and get_dos refactored to use solver kwargs helpers and structured cache keys. Band and DOS computations reuse cached accessors only when cache key matches, otherwise recompute and record the cache key for next comparison.
Integration tests for parameter forwarding and caching dptb/tests/test_postprocess_unified.py	Tests verify eig_solver alias support, forward nk and solver through the computation stack, confirm reuse when only nk changes, verify recomputation when solver or configuration changes, and validate ValueError when both solver and eig_solver are provided.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.53% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title 'fix(postprocess): normalize unified eigen solver options' accurately reflects the main objective of the changeset: normalizing/standardizing eigen solver options across the unified postprocess API layer.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@dptb/postprocess/unified/properties/dos.py`:
- Around line 175-179: PDOS mode currently logs ignored options for solver and
ill_threshold but not for ill_pad_value; update the PDOS path where data, eigs,
vecs = self._system.calculator.get_eigenstates(...) is called to also emit a
warning when ill_pad_value is not None (e.g., log.warning("ill_pad_value is
ignored for PDOS because eigenvector padding is not implemented.")) so callers
are informed; locate the block that checks solver and ill_threshold and add the
analogous check for ill_pad_value.

In `@dptb/postprocess/unified/system.py`:
- Around line 127-139: The bug is that _dos_cache_key omits the "dos_config"
entry when kmesh is None, causing different DOS requests with kmesh=None but
different erange/npts/etc. to collide; fix _dos_cache_key (the class method that
calls cls._eigen_cache_key and cls._normalize_cache_value) to always include a
normalized dos_config in the returned cache_key (use the full dict with "kmesh":
kmesh, "is_gamma_center": is_gamma_center, "erange": erange, "npts": npts,
"smearing": smearing, "sigma": sigma, "pdos": pdos, "extra_kwargs": extra_kwargs
or {}) so None is preserved and changes to other parameters prevent stale cache
hits.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 334a85b1-9394-41ed-a155-f21c61b5422b

📥 Commits

Reviewing files that changed from the base of the PR and between ee90982 and 0c74396.

📒 Files selected for processing (5)

• dptb/postprocess/unified/calculator.py
• dptb/postprocess/unified/properties/band.py
• dptb/postprocess/unified/properties/dos.py
• dptb/postprocess/unified/system.py
• dptb/tests/test_postprocess_unified.py