MDescriptor 0.2.3__tar.gz → 0.2.4__tar.gz

{mdescriptor-0.2.3 → mdescriptor-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: MDescriptor
-Version: 0.2.3
+Version: 0.2.4
 Summary: Batch-oriented periodic atomic descriptors with C++17 kernels
 License:                     GNU GENERAL PUBLIC LICENSE
                                 Version 3, 29 June 2007
@@ -687,6 +687,7 @@ Provides-Extra: sparse
 Requires-Dist: scipy>=1.11; extra == "sparse"
 Provides-Extra: test
 Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-cov>=7; extra == "test"
 Requires-Dist: ase>=3.22; extra == "test"
 Requires-Dist: scipy>=1.11; extra == "test"
 Provides-Extra: reference-dscribe
@@ -720,6 +721,7 @@ Requires-Dist: ase>=3.22; extra == "all"
 Requires-Dist: scipy>=1.11; extra == "all"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=7; extra == "dev"
 Requires-Dist: ase>=3.22; extra == "dev"
 Requires-Dist: scipy>=1.11; extra == "dev"
 Requires-Dist: ruff>=0.8; extra == "dev"
@@ -747,8 +749,10 @@ src/mdescriptor/descriptors/
   model_backed/               graph seam plus NEP, DPA4, DPA4C
 src/mdescriptor/models/assets/ packaged, hash-verified model resources
 tests/golden/              descriptor-owned, benchmark-independent accuracy fixtures
+docs/numerical-baselines.md  static-golden and external-runtime oracle inventory
 scripts/benchmarking/      controlled local benchmark runners
-benchmarks/                local-only benchmark snapshots (ignored by Git)
+benchmarks/                local benchmark snapshots (ignored except for tracked oracles)
+benchmarks/_legacy_oracles/ pinned independent upstream oracle adapters
 ```
 
 `standalone` descriptors never require a model file. `model_backed` descriptors
@@ -781,6 +785,23 @@ installing Torch; the supported default graphs run through the C++17/OpenMP
 backend and specialised configurations retain the NumPy fallback. No network
 model download is performed.
 
+可选的外部数值对照固定使用 `deepmd-kit==3.2.0`：
+
+```bash
+python -m pip install ".[reference-deepmd]"
+python -m pytest -m deepmd tests/external_reference/test_deepmd.py
+```
+
+该对照同时覆盖周期和非周期输入；非周期帧按 DeepMD 的 `cells=None` 语义传入。
+`tests/golden/dpa4*` 的 expected output（包括非周期行）也由该外部 evaluator 生成，
+manifest 记录了 evaluator 脚本、模型 hash 和 `deepmd-kit` 版本；运行时仍只加载已
+提交的 NPZ，不要求安装 DeepMD。
+
+所有 28 个描述符都登记在[数值基线清单](docs/numerical-baselines.md)，并都有外部
+静态 golden：7 个沿用独立上游/source NPZ，另外 21 个在对应目录的
+`external_manifest.json` 中保存固定版本 provider 生成的数值。默认测试只依赖提交的
+fixture；外部 provider 缺失或版本漂移会使 reference job 失败，而不会静默跳过。
+
 性能说明：DPA4 native 路径现在使用固定大小分块的 SGEMM、可复用的计算工作区，
 并只为每条边计算一次 attention logit；DPA4C 的类型对 MLP 采用每个 calculator
 实例独立的惰性缓存。OpenBLAS 仅作为构建依赖，官方 wheel 会内置 prefixed 的
@@ -957,7 +978,7 @@ For GUI configuration JSON, a model parameter may be an explicit path string
 or the tagged object returned by `ModelResource.to_dict()`; the latter is used
 for named/checksummed resources.
 
-The DPA4/DPA4C checkpoint readers and NumPy reference path remain isolated
+The DPA4/DPA4C checkpoint readers and NumPy fallback path remain isolated
 vendor adapters. The default inference graphs are lowered into the private
 `mdescriptor._native` C++17/OpenMP extension.
 
@@ -966,8 +987,19 @@ vendor adapters. The default inference graphs are lowered into the private
 ```bash
 .venv/bin/python -m pip install -e . --no-build-isolation
 .venv/bin/python -m pytest --import-mode=importlib tests -q
+.venv/bin/python -m pytest --cov=mdescriptor --cov-report=term-missing tests
+
+.venv/bin/cmake -S cpp/tests -B build/cpp-tests -DCMAKE_BUILD_TYPE=Release
+.venv/bin/cmake --build build/cpp-tests --config Release
+.venv/bin/ctest --test-dir build/cpp-tests -C Release --output-on-failure
 ```
 
+Coverage excludes the isolated vendored DPA implementation and enforces 75%
+branch coverage for project-owned Python code.  Tests marked `timing` record
+repeatable timing samples but intentionally do not impose a runner-dependent
+speedup threshold; controlled performance reports are produced by
+`scripts/run_benchmark.py`.
+
 The extension is private (`mdescriptor._native`). C++ shared math and batch
 helpers live in named headers under `cpp/include/mdescriptor/detail/`.
 

{mdescriptor-0.2.3 → mdescriptor-0.2.4}/README.md

@@ -19,8 +19,10 @@ src/mdescriptor/descriptors/
   model_backed/               graph seam plus NEP, DPA4, DPA4C
 src/mdescriptor/models/assets/ packaged, hash-verified model resources
 tests/golden/              descriptor-owned, benchmark-independent accuracy fixtures
+docs/numerical-baselines.md  static-golden and external-runtime oracle inventory
 scripts/benchmarking/      controlled local benchmark runners
-benchmarks/                local-only benchmark snapshots (ignored by Git)
+benchmarks/                local benchmark snapshots (ignored except for tracked oracles)
+benchmarks/_legacy_oracles/ pinned independent upstream oracle adapters
 ```
 
 `standalone` descriptors never require a model file. `model_backed` descriptors
@@ -53,6 +55,23 @@ installing Torch; the supported default graphs run through the C++17/OpenMP
 backend and specialised configurations retain the NumPy fallback. No network
 model download is performed.
 
+可选的外部数值对照固定使用 `deepmd-kit==3.2.0`：
+
+```bash
+python -m pip install ".[reference-deepmd]"
+python -m pytest -m deepmd tests/external_reference/test_deepmd.py
+```
+
+该对照同时覆盖周期和非周期输入；非周期帧按 DeepMD 的 `cells=None` 语义传入。
+`tests/golden/dpa4*` 的 expected output（包括非周期行）也由该外部 evaluator 生成，
+manifest 记录了 evaluator 脚本、模型 hash 和 `deepmd-kit` 版本；运行时仍只加载已
+提交的 NPZ，不要求安装 DeepMD。
+
+所有 28 个描述符都登记在[数值基线清单](docs/numerical-baselines.md)，并都有外部
+静态 golden：7 个沿用独立上游/source NPZ，另外 21 个在对应目录的
+`external_manifest.json` 中保存固定版本 provider 生成的数值。默认测试只依赖提交的
+fixture；外部 provider 缺失或版本漂移会使 reference job 失败，而不会静默跳过。
+
 性能说明：DPA4 native 路径现在使用固定大小分块的 SGEMM、可复用的计算工作区，
 并只为每条边计算一次 attention logit；DPA4C 的类型对 MLP 采用每个 calculator
 实例独立的惰性缓存。OpenBLAS 仅作为构建依赖，官方 wheel 会内置 prefixed 的
@@ -229,7 +248,7 @@ For GUI configuration JSON, a model parameter may be an explicit path string
 or the tagged object returned by `ModelResource.to_dict()`; the latter is used
 for named/checksummed resources.
 
-The DPA4/DPA4C checkpoint readers and NumPy reference path remain isolated
+The DPA4/DPA4C checkpoint readers and NumPy fallback path remain isolated
 vendor adapters. The default inference graphs are lowered into the private
 `mdescriptor._native` C++17/OpenMP extension.
 
@@ -238,8 +257,19 @@ vendor adapters. The default inference graphs are lowered into the private
 ```bash
 .venv/bin/python -m pip install -e . --no-build-isolation
 .venv/bin/python -m pytest --import-mode=importlib tests -q
+.venv/bin/python -m pytest --cov=mdescriptor --cov-report=term-missing tests
+
+.venv/bin/cmake -S cpp/tests -B build/cpp-tests -DCMAKE_BUILD_TYPE=Release
+.venv/bin/cmake --build build/cpp-tests --config Release
+.venv/bin/ctest --test-dir build/cpp-tests -C Release --output-on-failure
 ```
 
+Coverage excludes the isolated vendored DPA implementation and enforces 75%
+branch coverage for project-owned Python code.  Tests marked `timing` record
+repeatable timing samples but intentionally do not impose a runner-dependent
+speedup threshold; controlled performance reports are produced by
+`scripts/run_benchmark.py`.
+
 The extension is private (`mdescriptor._native`). C++ shared math and batch
 helpers live in named headers under `cpp/include/mdescriptor/detail/`.
 

{mdescriptor-0.2.3 → mdescriptor-0.2.4}/cpp/include/mdescriptor/descriptor.hpp

@@ -86,7 +86,7 @@ struct C00PSMlffOptions {
     int n_radial = 8;
     int l_max = 4;
     int cutoff_function = 0; // 0: BP, 1: MO, 2: RJ, 3: WMC
-    // Gaussian width sigma_atom in the VASP MLFF theory (Angstrom).  A
+    // Gaussian width sigma_atom in the reference MLFF convention (Angstrom).  A
     // positive value enables the Gaussian atomic distribution; zero keeps
     // the unsmoothed delta-distribution limit.
     double radial_sigma = 0.5;
@@ -97,7 +97,7 @@ struct C00PSMlffOptions {
     bool super_vector = false;
     double radial_weight = 1.0;
     double angular_weight = 1.0;
-    // VASP 6.6.0 MLFF LSIC semantics: subtract self terms only from PS
+    // Reference MLFF LSIC semantics: subtract self terms only from PS
     // channels whose neighbour species is the centre species.
     bool exclude_self_interaction = true;
     int num_threads = 0;

{mdescriptor-0.2.3 → mdescriptor-0.2.4}/cpp/src/standalone/c00ps_mlff.cpp

@@ -21,10 +21,10 @@ using detail::run_parallel_structures;
 
 constexpr double kPi = 3.141592653589793238462643383279502884;
 constexpr double kSqrtFourPi = 3.544907701811032054596334966682290365;
-// VASP 6.6.0 constructs the radial basis on NR equally spaced points and
+// The reference MLFF constructs the radial basis on NR equally spaced points and
 // normalizes it with the corresponding right-endpoint sum.  The same grid is
 // used here for the one-time basis setup.
-constexpr int kVaspRadialGridPoints = 10000;
+constexpr int kReferenceRadialGridPoints = 10000;
 constexpr int kRadialQuadraturePoints = 240;
 
 double spherical_bessel(int l, double x) {
@@ -136,7 +136,7 @@ double double_factorial_odd(int l) {
     return value;
 }
 
-// VASP's IL0 returns i_l(x) multiplied by exp(-W*s^2-W*r^2), evaluated in a
+// The reference radial integral returns i_l(x) multiplied by exp(-W*s^2-W*r^2), evaluated in a
 // form that remains finite for the Gaussian broadening integral.
 double scaled_modified_spherical_bessel(int l, double x, double w, double sample, double radius) {
     const double gaussian = std::exp(-w * (sample * sample + radius * radius));
@@ -280,8 +280,8 @@ void prepare_basis(
         for (int n = 0; n < radial_counts[static_cast<std::size_t>(l)]; ++n) {
             const double root = zeros[static_cast<std::size_t>(l)][static_cast<std::size_t>(n)];
             double norm2 = 0.0;
-            const double dr = options.r_cut / static_cast<double>(kVaspRadialGridPoints);
-            for (int point = 1; point <= kVaspRadialGridPoints; ++point) {
+            const double dr = options.r_cut / static_cast<double>(kReferenceRadialGridPoints);
+            for (int point = 1; point <= kReferenceRadialGridPoints; ++point) {
                 const double radius = static_cast<double>(point) * dr;
                 const double basis = spherical_bessel(l, root * radius / options.r_cut);
                 norm2 += radius * radius * basis * basis * dr;
@@ -294,11 +294,11 @@ void prepare_basis(
         return;
     }
 
-    // RAD_FUNC in VASP first convolves every normalized spherical Bessel
+    // The reference radial routine first convolves every normalized spherical Bessel
     // function with the Gaussian atom distribution and then tabulates the
     // result on the same radial mesh.  The integrand vanishes at both mesh
     // endpoints for the Bessel basis, so high-order Gauss integration matches
-    // VASP's right-endpoint grid sum to the precision needed here while
+    // The right-endpoint grid sum is retained to the precision needed here while
     // avoiding an O(NR^2) setup.
     std::vector<double> nodes;
     std::vector<double> weights;
@@ -306,7 +306,7 @@ void prepare_basis(
     const double width_parameter = 0.5 / (options.radial_sigma * options.radial_sigma);
     const double prefactor = 4.0 * kPi * std::pow(width_parameter / kPi, 1.5);
     const double quadrature_scale = 0.5 * options.r_cut;
-    const std::size_t table_width = static_cast<std::size_t>(kVaspRadialGridPoints + 1);
+    const std::size_t table_width = static_cast<std::size_t>(kReferenceRadialGridPoints + 1);
     for (int l = 0; l <= options.l_max; ++l) {
         const std::int32_t count = radial_counts[static_cast<std::size_t>(l)];
         auto& table = radial_values[static_cast<std::size_t>(l)];
@@ -323,9 +323,9 @@ void prepare_basis(
                     = spherical_bessel(l, root * radius / options.r_cut) / norm;
             }
         }
-        for (int point = 0; point <= kVaspRadialGridPoints; ++point) {
+        for (int point = 0; point <= kReferenceRadialGridPoints; ++point) {
             const double sample = options.r_cut * static_cast<double>(point)
-                / static_cast<double>(kVaspRadialGridPoints);
+                / static_cast<double>(kReferenceRadialGridPoints);
             const double cutoff = cutoff_value(options.cutoff_function, sample, options.r_cut);
             for (int n = 0; n < count; ++n) {
                 double integral = 0.0;
@@ -353,18 +353,18 @@ double radial_value(
     double distance
 ) {
     if (options.radial_sigma > 0.0) {
-        const std::size_t table_width = static_cast<std::size_t>(kVaspRadialGridPoints + 1);
+        const std::size_t table_width = static_cast<std::size_t>(kReferenceRadialGridPoints + 1);
         const auto& table = radial_values[static_cast<std::size_t>(l)];
         const double coordinate = std::max(0.0, std::min(1.0, distance / options.r_cut))
-            * static_cast<double>(kVaspRadialGridPoints);
-        const int left = std::min(kVaspRadialGridPoints - 1, static_cast<int>(coordinate));
+            * static_cast<double>(kReferenceRadialGridPoints);
+        const int left = std::min(kReferenceRadialGridPoints - 1, static_cast<int>(coordinate));
         const double fraction = coordinate - static_cast<double>(left);
         const auto value = [&](int point) {
-            const int bounded = std::max(0, std::min(kVaspRadialGridPoints, point));
+            const int bounded = std::max(0, std::min(kReferenceRadialGridPoints, point));
             return table[static_cast<std::size_t>(n) * table_width + static_cast<std::size_t>(bounded)];
         };
         // Four-point cubic interpolation keeps the tabulated path smooth and
-        // mirrors the cubic spline evaluation used by VASP's SPLVAL_ML_NEW.
+        // mirrors the reference cubic spline evaluation.
         const double p0 = value(left - 1);
         const double p1 = value(left);
         const double p2 = value(left + 1);
@@ -603,7 +603,7 @@ void C00PSMlffCalculator::compute(
                             * radial_count;
                         const double addition = (2.0 * l + 1.0) / (4.0 * kPi);
                         for (std::size_t neighbor = 0; neighbor < neighbor_count; ++neighbor) {
-                            // Match VASP 6.6.0 MLFF LSIC: only the centre
+                            // Match the reference MLFF LSIC: only the centre
                             // species receives a self-interaction correction.
                             if (types[neighbor] != center_type) {
                                 continue;
@@ -651,7 +651,7 @@ void C00PSMlffCalculator::compute(
                                 total -= self_power[
                                     self_power_offsets[static_cast<std::size_t>(l)] + pair_index];
                             }
-                            // VASP's WVAR distinguishes radial indices, not
+                            // The reference WVAR distinguishes radial indices, not
                             // flattened species/radial channels.  Therefore
                             // cross-species channels with equal radial index
                             // retain weight 1.0.

mdescriptor-0.2.4/cpp/tests/CMakeLists.txt

@@ -0,0 +1,19 @@
+cmake_minimum_required(VERSION 3.15...4.0)
+project(MDescriptorCppTests LANGUAGES CXX)
+
+include(CTest)
+find_package(OpenMP)
+
+add_executable(
+    mdescriptor_cpp_public_api
+    test_public_api.cpp
+    ../src/common/control.cpp
+    ../src/common/neighbor.cpp
+)
+target_compile_features(mdescriptor_cpp_public_api PRIVATE cxx_std_17)
+target_include_directories(mdescriptor_cpp_public_api PRIVATE ../include)
+if(OpenMP_CXX_FOUND)
+    target_link_libraries(mdescriptor_cpp_public_api PRIVATE OpenMP::OpenMP_CXX)
+endif()
+
+add_test(NAME cpp_public_api COMMAND mdescriptor_cpp_public_api)

mdescriptor-0.2.4/cpp/tests/test_public_api.cpp

@@ -0,0 +1,106 @@
+#include "mdescriptor/neighbor.hpp"
+
+#include <array>
+#include <cstdint>
+#include <iostream>
+#include <memory>
+#include <stdexcept>
+#include <string>
+
+namespace {
+
+void require(bool condition, const std::string& message) {
+    if (!condition) {
+        throw std::runtime_error(message);
+    }
+}
+
+template <typename Error, typename Function>
+void require_throws(Function&& function, const std::string& message) {
+    try {
+        function();
+    } catch (const Error&) {
+        return;
+    }
+    throw std::runtime_error(message);
+}
+
+mdescriptor::StructureBatchView isolated_pair() {
+    static const std::array<std::int32_t, 2> numbers{1, 8};
+    static const std::array<double, 6> positions{0.0, 0.0, 0.0, 1.0, 0.0, 0.0};
+    static const std::array<double, 9> cell{};
+    static const std::array<std::int32_t, 3> pbc{};
+    static const std::array<std::int64_t, 2> offsets{0, 2};
+    return {
+        numbers.data(), positions.data(), cell.data(), pbc.data(), offsets.data(), 1, 2,
+    };
+}
+
+void test_compute_control_contract() {
+    auto control = std::make_shared<mdescriptor::ComputeControl>();
+    control->reset(2);
+    require(control->total() == 2, "reset must publish the requested total");
+    require(control->completed() == 0, "reset must clear completed work");
+    require(!control->cancelled(), "reset must clear cancellation");
+    control->mark_completed();
+    require(control->completed() == 1, "mark_completed must advance progress");
+    control->cancel();
+    require(control->cancelled(), "cancel must be observable");
+    require_throws<std::invalid_argument>(
+        [&] { control->reset(-1); },
+        "negative work totals must be rejected");
+}
+
+void test_neighbor_graph_boundary_contract() {
+    const auto batch = isolated_pair();
+    const auto inclusive = mdescriptor::build_neighbor_graph(batch, 1.0, nullptr, 1, true);
+    require(inclusive.atoms() == 2, "graph must retain the batch atom count");
+    require(inclusive.offsets() == std::vector<std::int64_t>({0, 2, 4}),
+            "inclusive cutoff must retain self and boundary neighbor entries");
+    for (std::int64_t center = 0; center < 2; ++center) {
+        const auto neighbors = inclusive.for_center(center);
+        require(neighbors.size == 2, "each center must expose both atoms");
+        bool found_self = false;
+        bool found_boundary = false;
+        for (std::size_t index = 0; index < neighbors.size; ++index) {
+            found_self = found_self || neighbors.exact_self(index, center);
+            found_boundary = found_boundary || neighbors.distance2[index] == 1.0;
+        }
+        require(found_self, "neighbor views must identify exact self entries");
+        require(found_boundary, "inclusive cutoff must retain distance-equal neighbors");
+    }
+
+    const auto exclusive = mdescriptor::build_neighbor_graph(batch, 1.0, nullptr, 1, false);
+    require(exclusive.offsets() == std::vector<std::int64_t>({0, 1, 2}),
+            "exclusive cutoff must discard distance-equal neighbors");
+}
+
+void test_neighbor_graph_rejects_invalid_or_cancelled_work() {
+    auto mixed = isolated_pair();
+    const std::array<std::int32_t, 3> mixed_pbc{1, 0, 1};
+    mixed.pbc = mixed_pbc.data();
+    require_throws<std::invalid_argument>(
+        [&] { (void)mdescriptor::build_neighbor_graph(mixed, 1.0); },
+        "mixed periodicity must be rejected by the C++ boundary");
+
+    auto control = std::make_shared<mdescriptor::ComputeControl>();
+    control->reset(1);
+    control->cancel();
+    require_throws<mdescriptor::CancelledError>(
+        [&] { (void)mdescriptor::build_neighbor_graph(isolated_pair(), 1.0, control, 1); },
+        "pre-cancelled work must raise CancelledError");
+}
+
+} // namespace
+
+int main() {
+    try {
+        test_compute_control_contract();
+        test_neighbor_graph_boundary_contract();
+        test_neighbor_graph_rejects_invalid_or_cancelled_work();
+    } catch (const std::exception& error) {
+        std::cerr << "C++ public API test failed: " << error.what() << '\n';
+        return 1;
+    }
+    return 0;
+}

mdescriptor-0.2.4/docs/numerical-baselines.md

@@ -0,0 +1,49 @@
+# Numerical baselines / 数值基线
+
+The repository has a committed numerical golden for every descriptor.
+An `external_static` entry means the values came from an independent
+upstream/source oracle.  The 21 provider-backed entries keep the older
+project snapshot as a secondary contract fixture and add an
+`external_manifest.json` sidecar as the primary numerical oracle.
+The pinned provider tests remain a separate runtime smoke check.
+
+当前 28 个描述符全部有外部静态数值 golden：7 个沿用已提交的
+source-derived NPZ，另外 21 个由锁定版本的独立 provider 生成
+sidecar。21 个旧 project snapshot 仍保留，用于覆盖原有布局、
+metadata 与非周期契约；它们不再被冒充为 upstream 数值来源。
+
+| Descriptor | Committed golden | Independent oracle | Package/source | CI marker |
+|---|---|---|---|---|
+| `SOAP` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `SOAPTurbo` | external static | soap_turbo-master | `soap_turbo` (pinned source archive) | — |
+| `ACSF` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `ACE` | external static | ACE1.jl | `ACE1.jl` (0.12.5) | — |
+| `CoulombMatrix` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `SineMatrix` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `EwaldSumMatrix` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `MBTR` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `LMBTR` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `ValleOganov` | external static | DScribe | `dscribe` (2.1.2) | `dscribe` |
+| `AtomicComposition` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `NeighborList` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `SortedDistances` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `SphericalExpansion` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `SphericalExpansionByPair` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `SoapRadialSpectrum` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `SoapPowerSpectrum` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `LodeSphericalExpansion` | external static | Featomic | `featomic` (0.6.6) | `featomic` |
+| `EAD` | external static | PyXtal_FF | `pyxtal_ff` (0.2.3) | `pyxtalff` |
+| `SO3` | external static | PyXtal_FF | `pyxtal_ff` (0.2.3) | `pyxtalff` |
+| `SO4` | external static | PyXtal_FF | `pyxtal_ff` (0.2.3) | `pyxtalff` |
+| `SNAP` | external static | PyXtal_FF | `pyxtal_ff` (0.2.3) | `pyxtalff` |
+| `LBispectrum` | external static | LAMMPS/PyXtal_FF | `lammps + pyxtal_ff` (pinned source archive + 0.2.3) | — |
+| `MTP` | external static | MLIP-4 | `MLIP-4` (pinned source archive) | — |
+| `C00PSMLFF` | external static | licensed external MLFF | `local-only input` (user-supplied) | — |
+| `NEP` | external static | nep-adapters | `nep-adapters` (1.0.2) | `nepadapters` |
+| `DPA4` | external static | deepmd-kit | `deepmd-kit` (3.2.0) | `deepmd` |
+| `DPA4C` | external static | deepmd-kit | `deepmd-kit` (3.2.0) | `deepmd` |
+
+The NPZ comparisons check values and all result identity fields
+(`samples`, labels, level, structure ids and row offsets).  Contract,
+periodicity, symmetry and lifecycle tests remain separate because a
+numeric golden cannot prove those behaviours.

{mdescriptor-0.2.3 → mdescriptor-0.2.4}/pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
 [project.optional-dependencies]
 ase = ["ase>=3.22"]
 sparse = ["scipy>=1.11"]
-test = ["pytest>=8", "ase>=3.22", "scipy>=1.11"]
+test = ["pytest>=8", "pytest-cov>=7", "ase>=3.22", "scipy>=1.11"]
 reference-dscribe = ["pytest>=8", "ase==3.26.0", "scipy>=1.11", "dscribe==2.1.2"]
 reference-featomic = ["pytest>=8", "ase==3.26.0", "scipy>=1.11", "featomic==0.6.6"]
 reference-pyxtalff = [
@@ -46,7 +46,14 @@ reference-nepadapters = [
     "nep-adapters==1.0.2",
 ]
 all = ["ase>=3.22", "scipy>=1.11"]
-dev = ["pytest>=8", "ase>=3.22", "scipy>=1.11", "ruff>=0.8", "mypy>=1.13"]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=7",
+    "ase>=3.22",
+    "scipy>=1.11",
+    "ruff>=0.8",
+    "mypy>=1.13",
+]
 
 [tool.scikit-build]
 minimum-version = "1.0"
@@ -84,7 +91,18 @@ exclude = [
 build = "cp310-* cp311-* cp312-* cp313-* cp314-*"
 skip = "*-musllinux_* *-win32 *-*linux_i686"
 test-requires = ["pytest>=8", "ase>=3.22", "scipy>=1.11"]
-test-sources = ["tests", "scripts"]
+# The repository-level provenance tests read the checked-in metadata below;
+# include those files in cibuildwheel's isolated test tree so every wheel
+# platform exercises the same contract suite as the source checkout.
+test-sources = [
+    "tests",
+    "scripts",
+    "pyproject.toml",
+    "benchmarks/_legacy_oracles/sources.lock.json",
+    "benchmarks/_legacy_oracles/soapturbo",
+    "benchmarks/_legacy_oracles/lbispectrum",
+    "benchmarks/_legacy_oracles/mtp",
+]
 test-command = "python -m pytest --import-mode=importlib -m \"not reference\" tests && python scripts/verify_wheel.py"
 
 [tool.cibuildwheel.windows]
@@ -94,9 +112,11 @@ repair-wheel-command = "delvewheel repair --ignore-existing -w {dest_dir} -v {wh
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["."]
 addopts = "-m 'not reference'"
 markers = [
     "model: tests that exercise bundled model-backed descriptors and assets",
+    "timing: timing smoke tests that record runtimes without enforcing a speedup",
     "reference: tests that require a pinned external numerical reference implementation",
     "dscribe: external numerical comparisons against pinned DScribe",
     "featomic: external numerical comparisons against pinned Featomic",
@@ -105,6 +125,18 @@ markers = [
     "nepadapters: external numerical comparisons against pinned nep-adapters",
 ]
 
+[tool.coverage.run]
+branch = true
+source = ["mdescriptor"]
+omit = [
+    "*/mdescriptor/descriptors/model_backed/_vendor/*",
+]
+
+[tool.coverage.report]
+fail_under = 75
+show_missing = true
+skip_covered = true
+
 [tool.ruff]
 target-version = "py310"
 line-length = 100

mdescriptor-0.2.4/scripts/ace1_reference.jl

@@ -0,0 +1,55 @@
+"""
+Evaluate an ACE fixture directly through ACE1.jl.
+
+The first argument is a generated Julia input file defining the uppercase
+constants used below.  The second argument receives a plain-text matrix, one
+atom per row.  Keeping the transport format in Julia's standard library avoids
+adding a JSON or NumPy package to the archived ACE1.jl project.
+"""
+
+using ACE1
+using JuLIP
+
+include(ARGS[1])
+
+basis = ACE1.Utils.rpi_basis(
+    species=SPECIES,
+    N=N_ORDER,
+    r0=R0,
+    trans=ACE1.PolyTransform(TRANSFORM_P, TRANSFORM_R0),
+    wL=WL,
+    maxdeg=MAX_DEGREE,
+    D=DEGREES,
+    rcut=R_CUT,
+    rin=R_IN,
+    pcut=P_CUT,
+    pin=P_IN,
+    constants=CONSTANTS,
+    warn=false,
+)
+
+blocks = Matrix{Float64}[]
+for structure in 1:(length(OFFSETS) - 1)
+    first = OFFSETS[structure]
+    last = OFFSETS[structure + 1] - 1
+    atoms = JuLIP.Atoms(
+        NUMBERS[first:last],
+        permutedims(POSITIONS[first:last, :]);
+        cell=CELLS[structure],
+        pbc=Tuple(PBCS[structure, :]),
+    )
+    push!(blocks, Matrix(permutedims(ACE1.Descriptors.descriptors(basis, atoms))))
+end
+values = isempty(blocks) ? zeros(Float64, 0, 0) : vcat(blocks...)
+
+open(ARGS[2], "w") do output
+    println(output, size(values, 1), " ", size(values, 2))
+    for row in axes(values, 1)
+        println(output, join((repr(values[row, column]) for column in axes(values, 2)), " "))
+    end
+end
+
+println("ACE1=", Base.pkgversion(ACE1))
+println("JuLIP=", Base.pkgversion(JuLIP))
+println("Julia=", VERSION)
+