2026PKUCourseHW5:Fix file open check in utils.cpp

[derekyjy]

Reminder

• Have you linked an issue with this pull request?
• Have you added adequate unit tests and/or case tests for your pull request?
• Have you noticed possible changes of behavior below or in the linked issue?
• Have you explained the changes of codes in core modules of ESolver, HSolver, ElecState, Hamilt, Operator or Psi? (ignore if not applicable)

Linked Issue

Fix #...

Unit Tests and/or Case Tests for my changes

• A unit test is added for each new feature or bug fix.

What's changed?

• Example: My changes might affect the performance of the application under certain conditions, and I have tested the impact on various scenarios...

Any changes of core modules? (ignore if not applicable)

• Example: I have added a new virtual function in the esolver base class in order to ...

[Copilot]

Pull request overview

This PR introduces substantial Python/C++ binding expansions (PyABACUS ESolver + Driver scaffolding), refactors several pybind11 array-handling call sites via shared utilities, and updates CI/docs/examples across the repository—well beyond the stated “utils.cpp file open check” scope.

Changes:

• Add new PyABACUS esolver + driver Python packages, data containers, and build integration.
• Refactor multiple pybind11 bindings to use shared numpy validation/copy helpers and adjust some binding APIs.
• Update CI workflows, CMake find modules, docs, and add an ASE plugin + tests/examples.

Reviewed changes

Copilot reviewed 142 out of 3392 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
python/pyabacus/src/pyabacus/esolver/data_types.py	Add Python dataclasses for ESolver result/state containers
python/pyabacus/src/pyabacus/esolver/init.py	Export ESolver workflow/types and try-import C++ bindings
python/pyabacus/src/pyabacus/driver/init.py	Add Python driver facade and optional C++ binding import
python/pyabacus/src/pyabacus/init.py	Expose esolver/driver and convenience abacus() via lazy imports
python/pyabacus/src/pyabacus/ModuleNAO/_module_nao.py	Change lmax/rcut_max Python API shape via overload wrapper
python/pyabacus/src/py_numerical_radial.cpp	Use shared pybind utils for array checks/pointer access and return copies
python/pyabacus/src/hsolver/py_hsolver.cpp	Switch HSolver pybind bindings to adapter-based implementation; guard CG binding
python/pyabacus/src/hsolver/py_diago_dav_subspace.hpp	Adjust Davidson-subspace call signature (remove need_subspace argument)
python/pyabacus/src/hsolver/py_diago_cg.hpp	Update CG subspace callback signature
python/pyabacus/src/hsolver/CMakeLists.txt	Swap kernel source and add device helper source
python/pyabacus/src/ModuleNAO/py_m_nao.cpp	Use shared pybind utils; change lmax/rcut_max from properties to methods
python/pyabacus/src/ModuleNAO/CMakeLists.txt	Link device helper source
python/pyabacus/src/ModuleESolver/interfaces/i_scf_controller.hpp	Add SCF controller abstraction interface
python/pyabacus/src/ModuleESolver/interfaces/i_hamiltonian_builder.hpp	Add Hamiltonian builder interface and typed aliases
python/pyabacus/src/ModuleESolver/interfaces/i_diagonalizer.hpp	Add diagonalizer interface + config/result types
python/pyabacus/src/ModuleESolver/interfaces/i_charge_mixer.hpp	Add charge mixer interface + config and enum conversions
python/pyabacus/src/ModuleESolver/components/scf_controller_lcao.hpp	Add placeholder LCAO SCF controller implementation
python/pyabacus/src/ModuleESolver/CMakeLists.txt	Add _esolver_pack pybind target (header-only placeholder linking)
python/pyabacus/src/ModuleDriver/py_driver.hpp	Add C++ driver API skeleton + CalculationResult container
python/pyabacus/src/ModuleDriver/CMakeLists.txt	Disable driver build (subprocess fallback)
python/pyabacus/src/ModuleBase/CMakeLists.txt	Link device helper source
python/pyabacus/pyproject.toml	Raise Python/pybind11 minimum versions
python/pyabacus/examples/lcao_workflow_example.py	Add ESolver workflow usage examples
python/pyabacus/CONTRIBUTING.md	Update example CMake snippet to new kernel filename
python/pyabacus/CMakeLists.txt	Add ModuleESolver and optional ModuleDriver build option
interfaces/README	Add top-level interfaces README
interfaces/PYATB_interface/README	Add placeholder interface README
interfaces/HefeiNAMD_interface/README	Add placeholder interface README
interfaces/Candela_interface/README	Add placeholder interface README
interfaces/ASE_interface/tests/xtest.sh	Add ASE interface test runner script
interfaces/ASE_interface/tests/scf.py	Add ASE SCF integration test
interfaces/ASE_interface/tests/relax.py	Add ASE relax integration test
interfaces/ASE_interface/tests/md.py	Add ASE MD integration test
interfaces/ASE_interface/tests/band.py	Add ASE SCF+NSCF/band integration test
interfaces/ASE_interface/pyproject.toml	Add abacuslite packaging metadata
interfaces/ASE_interface/examples/scf.py	Add ASE SCF example
interfaces/ASE_interface/examples/relax.py	Add ASE relax example
interfaces/ASE_interface/examples/neb.py	Add ASE NEB example
interfaces/ASE_interface/examples/metadynamics.py	Add ASE metadynamics example
interfaces/ASE_interface/examples/md.py	Add ASE MD example
interfaces/ASE_interface/examples/dos.py	Add ASE DOS example
interfaces/ASE_interface/examples/constraintmd.py	Add ASE constrained MD example
interfaces/ASE_interface/examples/cellrelax.py	Add ASE cell-relax example
interfaces/ASE_interface/examples/bandstructure.py	Add ASE bandstructure example
interfaces/ASE_interface/abacuslite/xtest.sh	Add unit-test runner for abacuslite package
interfaces/ASE_interface/abacuslite/io/testfiles/nspin4-gamma-mddump	Add IO parsing fixture
interfaces/ASE_interface/abacuslite/io/testfiles/nspin4-gamma-eigocc	Add IO parsing fixture
interfaces/ASE_interface/abacuslite/io/testfiles/lcao-symm1-nspin1-multik-scf	Add IO parsing fixture
interfaces/ASE_interface/abacuslite/io/testfiles/input-script	Add IO parsing fixture
interfaces/ASE_interface/abacuslite/init.py	Add package init for abacuslite
interfaces/ASE_interface/README.md	Add ASE interface documentation
interfaces/ASE_interface/DEVELOP.md	Add developer guide for abacuslite internals
examples/relax/pw_output/KPT	Add trailing newline
examples/relax/pw_output/INPUT	Update example parameters/output controls
examples/relax/lcao_output/INPUT	Update example parameters/output controls
examples/36_gpu/si16_pw/INPUT	Update mixing_beta example
examples/36_gpu/si16_lcao/KPT	Update k-mesh and guidance comments
examples/36_gpu/si16_lcao/INPUT	Update GPU example parameters/comments
examples/19_dftu/NiO/INPUT	Remove out_bandgap setting
examples/04_noncollinear/BCC_Fe_NC_ground_state/reference/scf.output.ref	Update operator names in reference output
examples/03_spin_polarized/FM/reference/scf.output.ref	Update operator names in reference output
examples/03_spin_polarized/FM/reference/running_scf.log.ref	Update operator names in reference output
examples/03_spin_polarized/ATOM/reference/scf.output.ref	Update operator names in reference output
examples/03_spin_polarized/ATOM/reference/running_scf.log.ref	Update operator names in reference output
examples/03_spin_polarized/ATOM/INPUT	Remove out_bandgap setting
examples/03_spin_polarized/AFM/reference/scf.output.ref	Update operator names in reference output
examples/03_spin_polarized/AFM/reference/running_scf.log.ref	Update operator names in reference output
doxygen/Doxyfile	Set DOT_NUM_THREADS to 2
docs/requirements.txt	Add pyyaml dependency
docs/quick_start/input.md	Expand parameter-help docs and STRU note
docs/conf.py	Add theme TOC options + auto-generate input docs from YAML
docs/community/faq.md	Expand community contact + SOC FAQ answer
docs/advanced/scf/spin.md	Restructure noncolin/lspinorb explanation; add SOC details
docs/advanced/scf/initialization.md	Document init_chg dm/hr modes
docs/advanced/pp_orb.md	Add SOC pseudopotential guidance
docs/advanced/output_files/running_scf.log.md	Update operator names in docs example
docs/advanced/opt.md	Document relax_new implementations and algorithm availability
docs/advanced/md.md	Add NEP section
docs/advanced/interface/index.rst	Add pyabacus to interface index
docs/advanced/interface/ase.md	Replace legacy ASE interface docs with abacuslite guide
docs/advanced/interface/TB2J.md	Remove out_bandgap setting
docs/advanced/install.md	Add NEP build instructions
docs/advanced/input_files/stru.md	Add extra PP link + clarify velocity usage + add lambda/sc notes
docs/advanced/input_files/kpt.md	Add k-point weights + symmetry notes
docs/advanced/elec_properties/position_matrix.md	Replace out_interval with out_freq_ion
docs/advanced/elec_properties/hs_matrix.md	Replace out_interval with out_freq_ion
docs/advanced/elec_properties/density_matrix.md	Document DM(R) CSR output and restart usage
docs/advanced/elec_properties/Mulliken.md	Replace out_interval with out_freq_ion
docs/advanced/acceleration/cuda.md	Clarify single vs multi-GPU usage; update arch guidance
docs/CONTRIBUTING.md	Document YAML-driven INPUT parameter docs workflow
docs/CITATIONS.md	Fix author spelling in citation
cmake/Testing.cmake	Add/modify testing infra with FetchContent fallbacks
cmake/SetupCuSolverMp.cmake	Add cuSolverMp dependency setup with version-based backend selection
cmake/FindNEP.cmake	Add NEP (CPU) find module
cmake/FindMKL.cmake	Adjust MKL discovery/targets and add iomp5 target
cmake/FindLibRI.cmake	Update LibRI download URL
cmake/FindFFTW3.cmake	Extract FFTW version string from header
cmake/FindCereal.cmake	Change cereal FetchContent URL to a fork
cmake/BuildInfo.cmake	Add build-info header generation helper
Dockerfile.gnu	Remove duplicate bc install
Dockerfile.cuda	Remove duplicate bc install
.github/workflows/version_check.yml	Update checkout action version and tag/code version matching logic
.github/workflows/test.yml	Update checkout action version; change test invocation to direct ctest
.github/workflows/pytest.yml	Update checkout/setup-python action versions
.github/workflows/performance.yml	Update checkout action version
.github/workflows/dynamic.yml	Update checkout action version
.github/workflows/doxygen.yml	Update checkout/upload artifact action versions
.github/workflows/devcontainer.yml	Add workspace cleanup steps; update checkout action version
.github/workflows/cuda.yml	Update checkout action version; ensure clean build dir
.github/workflows/coverage.yml	Update checkout action version; revamp coverage tool install and collection
.github/workflows/build_test_makefile.yml	Update checkout action version; adjust make invocation
.github/workflows/build_test_cmake.yml	Fix build args typos; update checkout action version; set PEXSI env
.github/workflows/ase_plugin_test.yml	Add CI workflow to build ABACUS and run abacuslite tests

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The PR title/description indicate a small fix (“Fix file open check in utils.cpp”), but the diff introduces large new modules (PyABACUS ESolver/Driver, ASE interface, CI/CMake/docs changes). Please update the PR title/description (and linked issue) to match the actual scope, or split into smaller PRs (e.g., bindings, docs, CI) to keep reviewability and traceability.

[Copilot]

This changes lmax/rcut_max from property-style access (no-arg) to a callable method, which is a breaking API change for downstream Python code that previously did obj.lmax (int) rather than obj.lmax(). Consider keeping backward compatibility by preserving the property names and introducing new methods for the indexed forms (e.g., lmax_of_type(itype) / rcut_max_of_type(itype)), or provide distinct attribute names for no-arg vs indexed access.

[Copilot]

The bindings remove def_property_readonly(\"lmax\"/\"rcut_max\") and replace them with overloadable methods, which breaks existing Python usage expecting collection.lmax as an attribute. If compatibility matters, bind lmax/rcut_max properties under their original names and expose the indexed versions under new method names (or vice versa), rather than changing the existing meaning of the attribute.

[Copilot]

std::runtime_error is used in this header but <stdexcept> is not included anywhere in this file (and the included headers shown don’t guarantee it). This can cause compilation errors depending on include order. Add #include <stdexcept> in this header.

[Copilot]

This header uses std::pair but does not include <utility> (or another header that guarantees std::pair is declared). This can fail to compile in some environments. Add #include <utility>.

Suggested change

	#include <functional>
	#include <functional>
	#include <utility>

[Copilot]

Using GIT_TAG \"origin/main\" makes builds non-reproducible and can break unexpectedly as upstream changes. Pin FetchContent dependencies to a specific release tag or commit SHA (mandatory for deterministic CI and safer supply-chain behavior).

[Copilot]

This switches the cereal source to a fork (MCresearch/cereal) and tracks master, which is both a supply-chain risk and non-reproducible. Prefer the official upstream repository (USCiLab/cereal) and pin to a specific tagged release or commit SHA. If the fork is required, document why and pin a specific commit.

Suggested change

	URL https://codeload.github.com/MCresearch/cereal/tar.gz/master
	# Use official upstream cereal and pin to a specific release for reproducibility.
	URL https://codeload.github.com/USCiLab/cereal/tar.gz/v1.3.2

[Copilot]

silicon.calc = abacus (and the subsequent energy/optimization) is outside the TemporaryDirectory() context. This means abacus.directory may already be deleted when the calculation runs, causing failures or writing into a non-existent path. Indent lines 38+ so the calculation runs inside the with tempfile.TemporaryDirectory() block.

Suggested change

	silicon.calc = abacus
	e = silicon.get_potential_energy()
	opt = BFGS(silicon)
	opt.run(fmax=0.05, steps=1)
	self.assertLessEqual(silicon.get_potential_energy(), e)
	self.assertIsNotNone(silicon.calc.results['forces'])
	self.assertIsNotNone(silicon.calc.results['stress'])
	silicon.calc = abacus
	e = silicon.get_potential_energy()
	opt = BFGS(silicon)
	opt.run(fmax=0.05, steps=1)
	self.assertLessEqual(silicon.get_potential_energy(), e)
	self.assertIsNotNone(silicon.calc.results['forces'])
	self.assertIsNotNone(silicon.calc.results['stress'])

[Copilot]

Same as relax.py: the MD setup and run occur after leaving the TemporaryDirectory() scope, so the working directory may be removed before ABACUS is invoked. Move lines 41+ inside the with tempfile.TemporaryDirectory() block.

Suggested change

	silicon.calc = abacus
	MaxwellBoltzmannDistribution(silicon, temperature_K=300)
	dyn = Langevin(silicon,
	timestep=1.0 * fs,
	temperature_K=300,
	friction=0.01)
	dyn.run(2)
	silicon.calc = abacus
	MaxwellBoltzmannDistribution(silicon, temperature_K=300)
	dyn = Langevin(
	silicon,
	timestep=1.0 * fs,
	temperature_K=300,
	friction=0.01,
	)
	dyn.run(2)

[Copilot]

Fix spelling: 'paramerters' -> 'parameters'.

[Flying-dragon-boxing]

Please submit your PR in deepmodeling/abacus-develop.