Arc-based Clone for LibXCFunctional; graceful libxc 6.x ext-param handling; CPU version-matrix CI - #2
Merged
Conversation
LibXCFunctional now holds its raw `xc_func_type` behind an Arc in a private LibXCFuncRaw handle (which owns the Drop and the unsafe Send/Sync impls): - Clone is cheap and shares the C object (no FFI-level re-initialization); the object is released when the last handle drops. - Sharing for parallel evaluation is lock-free: all libxc read/compute entry points take `const xc_func_type *` and do not write through it, so concurrent compute/getters through clones are data-race-free (verified against the libxc dispatch sources). - To keep this sound with Clone, every mutating setter now additionally requires Arc uniqueness (checked via Arc::get_mut): while any clone is alive, setters fail with the new LibXCError::SharedError (or panic, for the non-`_f` variants). Threshold setters gained fallible `_f` variants following the crate convention. Add tests/general/test_clone.rs covering: shared identity of clones, rayon parallel evaluation (LDA/GGA/hybrid/MGGA, both sharing by reference and cloning into jobs), raw OS-thread sending, setter exclusivity, and static Send/Sync assertions. Update ARCHITECTURE.md accordingly. Co-authored-by: Claude Code <noreply@anthropic.com> Co-authored-by: glm-5 <service@zhipuai.cn>
The xc_func_get_ext_params* getters were introduced in libxc v7.0 (see
versioning_xc.md); libxc 6.x keeps current values only in per-functional
storage with no uniform read-back (its own by-name setter passes the
XC_EXT_PARAMS_DEFAULT sentinel for unspecified parameters). Reading
current values on a 6.x library therefore panicked with an opaque
Option::unwrap from the dyload shim — and segfaulted outright when a
second libxc version was also discoverable (e.g. a conda env), because
symbols resolved from both libraries mix ABI layouts.
- Add LibXCError::UnsupportedVersion { needed, found }.
- ext_param_values/ext_param_map gain fallible _f variants that return
UnsupportedVersion on libxc < 7.0; the non-_f variants panic with a
clear version message instead of the dyload unwrap.
- describe() degrades to default ext-param values (with a note) on
libxc < 7.0 instead of panicking.
- set_ext_param_map falls back to defaults as the base map on libxc < 7.0,
matching libxc 6.x semantics where setting one parameter resets the
others to defaults.
- Guard read-back assertions in doctests and tests by version; add
test_ext_param_values_version_behavior.
Validated against 7.0.0, 7.1.2, and 6.2.2 (clean environment: unset
CONDA_PREFIX so the conda libxc is not mixed in).
Co-authored-by: Claude Code <noreply@anthropic.com>
Co-authored-by: glm-5 <service@zhipuai.cn>
…l doc - LibXCError is now #[non_exhaustive]: new variants (SharedError, UnsupportedVersion were just added) may arrive in patch releases, so downstream matches should include a wildcard arm. With this in place, variant additions are no longer API-breaking. - Bump workspace version to 0.1.4 (libxc and libxc-ffi share it) and add the v0.1.4 changelog entry (Arc-based Clone with sound lock-free Send/Sync, setter exclusivity via SharedError, graceful <7.0 ext-param value getters via UnsupportedVersion). - cuda-testing skill doc: correct the claim that the `cuda` feature implies `api-v7_1` (it does not; `cuda = ["dep:cudarc"]`). Running the default api-v7_0 bindings against a v7.1+ CUDA library makes every functional report OnDevice (xc_func_init defers to the build's default flags), failing the CPU-guard tests. Document the correct invocation: `--features cuda,api-v7_1` (verified: full suite passes against 7.1.2-cuda). Co-authored-by: Claude Code <noreply@anthropic.com> Co-authored-by: glm-5 <service@zhipuai.cn>
Replace the single-version v7.0 workflow with a matrix that installs a pinned conda-forge libxc per leg and points LIBXC_DYLOAD at it, testing each version against its matching api-vX_Y feature set. Co-authored-by: Claude Code <noreply@anthropic.com> Co-authored-by: glm-5.3-flash <service@zhipuai.cn>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
LibXCFunctionalis nowClone: clones are reference-counted (Arc) handles to the same underlying C functional — no FFI-level re-initialization — so a functional can be shared across rayon workers lock-free. The unsafeSend/Syncimpls moved to the private owning handle, with soundness argued from libxc'sconst xc_func_type *read-side API.Arcuniqueness: while any clone is alive they returnLibXCError::SharedError(non-_fvariants panic). Threshold setters gained fallible_fvariants.xc_func_get_ext_params*does not exist there): newLibXCError::UnsupportedVersioninstead of an opaque panic/segfault;describe()degrades to defaults;set_ext_param_mapseeds from defaults (matches 6.x semantics).LibXCErrormarked#[non_exhaustive]; version bumped to 0.1.4.LIBXC_DYLOADwith its matchingapi-vX_Yfeature set.Test plan
api-v7_1, 0 failed), 6.2.2 clean-env (35 general + 41 doctests), CUDA (cuda,api-v7_1full suite)cargo fmt --checktest-cpumatrix green on 6.2.2 / 7.0.0 / 7.1.2clippy/rustfmtgreen