Make HelFEM consumable: split the library, install the diatomic headers, namespace the include root

[susilehtola]

Another project wants HelFEM's diatomic coordinate machinery and its Coulomb/exchange builders. It couldn't have them. This makes that work, and fixes two related problems found along the way.

The findings come from building an install tree and inventorying it, plus writing a standalone consumer against it — not from reading CMakeLists.txt.

1. The gate was all-or-nothing, and the dependency it forced was fictitious

add_subdirectory(src) sat inside if(HELFEM_BINARIES), so obtaining a diatomic TwoDBasis meant building twelve executables and hard-requiring HDF5 + libxc — both PUBLIC on helfem-common, hence inherited by the consumer.

The diatomic basis uses neither. Of ~25 translation units in helfem-common, exactly nine touch HDF5 or libxc (checkpoint, dftfuncs, dftgrid*, atomdb, sadatom/*). None is in the diatomic path, whose entire closure is clean:

general/scf_helpers.cpp  clean     general/gaunt.cpp               clean
general/gsz.cpp          clean     general/spherical_harmonics.cpp clean
general/timer.cpp        clean     diatomic/quadrature.cpp         clean

One library mixing basis machinery with DFT and checkpointing lets its heaviest member set everyone's requirements.

So: helfem-fem, built unconditionally, carrying the geometry machinery. src/ is entered always and gates only the HDF5/libxc half. helfem-common keeps the rest and links helfem-fem rather than duplicating it.

The atomic basis does not join it. general/model_potential.cpp uses libxc's XC_LDA_X for the SAP potential, and atomic/TwoDBasis.h includes it. Making that optional would let atomic follow; the exclusion and its reason are recorded in src/CMakeLists.txt rather than the split quietly shipping narrower than described.

2. No diatomic headers were installed

include/helfem/ shipped atomic/TwoDBasis.h and four general/ headers, nothing else — so even with HELFEM_BINARIES=ON and helfem-common linked, there was no basis.h to include. The atomic side got this treatment for libatomscf; diatomic never did. Added, preserving the source layout so the relative-include chain in basis.h resolves unchanged.

3. The header layout could shadow a system header

libhelfem installed 37 headers flat into include/ — among them math.h, types.h, grid.h — and handed consumers -I${prefix}/include. Since -I paths precede system paths, a consumer's #include <math.h> resolved to HelFEM's, which then includes <types.h> expecting its own.

Everything now lands under include/helfem/, and the 204 include lines naming those headers across 102 files were rewritten to <helfem/X.h>. include/ holds exactly one entry: helfem/. The bare $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}> entry goes with it — it existed so a stale helfem.h at the binary root could be found, which is the same shadowing inside the build tree.

What the consumer test caught

A standalone project — find_package + helfem::fem + <helfem/diatomic/basis.h>, with no HelFEM source directory on its include path — turned up three further packaging faults that reading the CMake would not have:

fault	effect
helfemConfig.cmake required OpenOrbitalOptimizer unconditionally	find_package(helfem) failed outright on a HELFEM_BINARIES=OFF install
helfem_otr exported unconditionally	dangling OpenTrustRegion::opentrustregion in that same install
export set published helfem::helfem-fem	EXPORT_NAME now gives the helfem::fem the in-tree alias promises, archive still libhelfem-fem.a

It is committed as examples/diatomic_consumer.cpp, next to the existing atomic example, so the packaging has a regression guard instead of living in a scratch directory.

Verification

HELFEM_BINARIES=OFF   build rc 0, no HDF5 / libxc in the configure
consumer              Nbf=101  |S|=3.40e+03  |H|=3.59e+02  |J|=3.05e+04  |K|=4.34e+03  OK
HELFEM_BINARIES=ON    build rc 0
ctest -L unit         9/9
ctest (full enabled)  exit 0 — no failures

Nbf=101 is what the in-tree diatomic tests report on the same grid, so the basis is genuinely constructed rather than trivially empty. The full suite matters here because the integration cases run real SCF calculations: if any of the 204 rewritten includes had picked up a different header, the energies would have moved.

🤖 Generated with Claude Code