MDescriptor 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: MDescriptor
-Version: 0.2.2
+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,18 +687,41 @@ 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
-Requires-Dist: pytest>=8; extra == "reference"
-Requires-Dist: ase==3.26.0; extra == "reference"
-Requires-Dist: scipy>=1.11; extra == "reference"
-Requires-Dist: dscribe==2.1.2; extra == "reference"
+Provides-Extra: reference-dscribe
+Requires-Dist: pytest>=8; extra == "reference-dscribe"
+Requires-Dist: ase==3.26.0; extra == "reference-dscribe"
+Requires-Dist: scipy>=1.11; extra == "reference-dscribe"
+Requires-Dist: dscribe==2.1.2; extra == "reference-dscribe"
+Provides-Extra: reference-featomic
+Requires-Dist: pytest>=8; extra == "reference-featomic"
+Requires-Dist: ase==3.26.0; extra == "reference-featomic"
+Requires-Dist: scipy>=1.11; extra == "reference-featomic"
+Requires-Dist: featomic==0.6.6; extra == "reference-featomic"
+Provides-Extra: reference-pyxtalff
+Requires-Dist: pytest>=8; extra == "reference-pyxtalff"
+Requires-Dist: ase==3.26.0; extra == "reference-pyxtalff"
+Requires-Dist: scipy>=1.11; extra == "reference-pyxtalff"
+Requires-Dist: numba>=0.50.1; extra == "reference-pyxtalff"
+Requires-Dist: pyxtal_ff==0.2.3; extra == "reference-pyxtalff"
+Provides-Extra: reference-deepmd
+Requires-Dist: pytest>=8; extra == "reference-deepmd"
+Requires-Dist: ase==3.26.0; extra == "reference-deepmd"
+Requires-Dist: scipy>=1.11; extra == "reference-deepmd"
+Requires-Dist: deepmd-kit[torch]==3.2.0; extra == "reference-deepmd"
+Provides-Extra: reference-nepadapters
+Requires-Dist: pytest>=8; extra == "reference-nepadapters"
+Requires-Dist: ase==3.26.0; extra == "reference-nepadapters"
+Requires-Dist: scipy>=1.11; extra == "reference-nepadapters"
+Requires-Dist: nep-adapters==1.0.2; extra == "reference-nepadapters"
 Provides-Extra: all
 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"
@@ -726,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
@@ -760,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 的
@@ -796,7 +838,8 @@ batch = StructureBatch(
 )
 ```
 
-`StructureBatch` validates contiguous arrays, finite positions/cells,
+`StructureBatch` takes an owned, read-only snapshot of its contiguous arrays
+and validates integer fields before narrowing, finite positions/cells,
 nonsingular cells, positive atomic numbers, monotonic offsets and fully
 periodic `pbc == (1, 1, 1)`. ASE conversion is available through
 `StructureBatch.from_ase(...)`.
@@ -841,7 +884,51 @@ Instances are synchronous and not promised to be thread-safe.
 `structure_ids`, row offsets, stable `labels`, JSON-safe `metadata`, per-row
 `samples`, and `feature_count`. The descriptor itself also retains the latest
 JSON-safe `metadata` and its `configuration` after `close()`. The standard shapes are `(N, F)`, `(S, F)`,
-and `(P, F)` for atom, structure and pair outputs respectively.
+and `(P, F)` for atom, structure and pair outputs respectively. Result arrays
+are owned snapshots and exposed read-only.
+
+## Supported descriptors / 支持的描述符
+
+The built-in registry currently provides 28 descriptors. `None` means no model
+file is needed; `Optional` means a model can be supplied (as with MTP); and
+`Required` means the descriptor always resolves a local model resource. See
+the [full descriptor inventory](docs/descriptor-inventory.md) for parameters,
+capabilities and backend details.
+
+内置注册表目前提供 28 个描述符。`None` 表示不需要模型文件；`Optional` 表示
+可以提供模型（例如 MTP）；`Required` 表示描述符始终解析本地模型资源。参数、
+能力和后端详情请参阅[完整描述符清单](docs/descriptor-inventory.md)。
+
+| Descriptor / 描述符 | Category / 类型 | Output / 输出 | Model / 模型 |
+|---|---|---|---|
+| `SOAP` | Local / 局部 | Structure / 结构 | `None` |
+| `SOAPTurbo` | Local / 局部 | Atom / 原子 | `None` |
+| `ACSF` | Local / 局部 | Atom / 原子 | `None` |
+| `ACE` | Local / 局部 | Atom / 原子 | `None` |
+| `CoulombMatrix` | Matrix / 矩阵 | Structure / 结构 | `None` |
+| `SineMatrix` | Matrix / 矩阵 | Structure / 结构 | `None` |
+| `EwaldSumMatrix` | Matrix / 矩阵 | Structure / 结构 | `None` |
+| `MBTR` | Many-body / 多体 | Structure / 结构 | `None` |
+| `LMBTR` | Many-body / 多体 | Atom / 原子 | `None` |
+| `ValleOganov` | Many-body / 多体 | Structure / 结构 | `None` |
+| `AtomicComposition` | Local / 局部 | Structure / 结构 | `None` |
+| `NeighborList` | Local / 局部 | Pair / 原子对 | `None` |
+| `SortedDistances` | Local / 局部 | Atom / 原子 | `None` |
+| `SphericalExpansion` | Local / 局部 | Atom / 原子 | `None` |
+| `SphericalExpansionByPair` | Local / 局部 | Pair / 原子对 | `None` |
+| `SoapRadialSpectrum` | Local / 局部 | Atom / 原子 | `None` |
+| `SoapPowerSpectrum` | Local / 局部 | Atom / 原子 | `None` |
+| `LodeSphericalExpansion` | Local / 局部 | Atom / 原子 | `None` |
+| `EAD` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `SO3` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `SO4` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `SNAP` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `LBispectrum` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `MTP` | Local / 局部 | Atom / 原子 | `Optional` |
+| `C00PSMLFF` | Local / 局部 | Atom / 原子 | `None` |
+| `NEP` | Model-backed / 模型 | Atom / 原子 | `Required` |
+| `DPA4` | Model-backed / 模型 | Atom / 原子 | `Required` |
+| `DPA4C` | Model-backed / 模型 | Atom / 原子 | `Required` |
 
 ## Registry / 注册表
 
@@ -853,6 +940,8 @@ import mdescriptor
 from mdescriptor.descriptors import SOAP
 
 print(mdescriptor.list_descriptors())
+metadata = mdescriptor.describe_descriptor("SOAP")
+runtime = mdescriptor.get_runtime_info()
 soap = SOAP(species=[1, 8], r_cut=4.5, n_max=2, l_max=2)
 rebuilt = mdescriptor.create_descriptor(soap.configuration)
 
@@ -863,7 +952,10 @@ child.register(my_spec)
 The built-in list separates `AssetPolicy.NONE`, `OPTIONAL` (for example MTP
 potentials), and `REQUIRED` (NEP/DPA4/DPA4C). The root package exposes stable
 contracts, registry functions and errors only; algorithm implementations are
-not re-exported from the root.
+not re-exported from the root. `describe_descriptor(name)` reads static,
+JSON-safe GUI metadata from the registry without constructing a descriptor or
+resolving a model. `get_runtime_info()` reports the package and contract
+schema versions, including `result_schema_version`.
 
 ## Model resources / 模型资源
 
@@ -882,7 +974,11 @@ dpa4 = DPA4(
 result = dpa4.compute(batch)
 ```
 
-The DPA4/DPA4C checkpoint readers and NumPy reference path remain isolated
+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 fallback path remain isolated
 vendor adapters. The default inference graphs are lowered into the private
 `mdescriptor._native` C++17/OpenMP extension.
 
@@ -891,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.2 → 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 的
@@ -89,7 +108,8 @@ batch = StructureBatch(
 )
 ```
 
-`StructureBatch` validates contiguous arrays, finite positions/cells,
+`StructureBatch` takes an owned, read-only snapshot of its contiguous arrays
+and validates integer fields before narrowing, finite positions/cells,
 nonsingular cells, positive atomic numbers, monotonic offsets and fully
 periodic `pbc == (1, 1, 1)`. ASE conversion is available through
 `StructureBatch.from_ase(...)`.
@@ -134,7 +154,51 @@ Instances are synchronous and not promised to be thread-safe.
 `structure_ids`, row offsets, stable `labels`, JSON-safe `metadata`, per-row
 `samples`, and `feature_count`. The descriptor itself also retains the latest
 JSON-safe `metadata` and its `configuration` after `close()`. The standard shapes are `(N, F)`, `(S, F)`,
-and `(P, F)` for atom, structure and pair outputs respectively.
+and `(P, F)` for atom, structure and pair outputs respectively. Result arrays
+are owned snapshots and exposed read-only.
+
+## Supported descriptors / 支持的描述符
+
+The built-in registry currently provides 28 descriptors. `None` means no model
+file is needed; `Optional` means a model can be supplied (as with MTP); and
+`Required` means the descriptor always resolves a local model resource. See
+the [full descriptor inventory](docs/descriptor-inventory.md) for parameters,
+capabilities and backend details.
+
+内置注册表目前提供 28 个描述符。`None` 表示不需要模型文件；`Optional` 表示
+可以提供模型（例如 MTP）；`Required` 表示描述符始终解析本地模型资源。参数、
+能力和后端详情请参阅[完整描述符清单](docs/descriptor-inventory.md)。
+
+| Descriptor / 描述符 | Category / 类型 | Output / 输出 | Model / 模型 |
+|---|---|---|---|
+| `SOAP` | Local / 局部 | Structure / 结构 | `None` |
+| `SOAPTurbo` | Local / 局部 | Atom / 原子 | `None` |
+| `ACSF` | Local / 局部 | Atom / 原子 | `None` |
+| `ACE` | Local / 局部 | Atom / 原子 | `None` |
+| `CoulombMatrix` | Matrix / 矩阵 | Structure / 结构 | `None` |
+| `SineMatrix` | Matrix / 矩阵 | Structure / 结构 | `None` |
+| `EwaldSumMatrix` | Matrix / 矩阵 | Structure / 结构 | `None` |
+| `MBTR` | Many-body / 多体 | Structure / 结构 | `None` |
+| `LMBTR` | Many-body / 多体 | Atom / 原子 | `None` |
+| `ValleOganov` | Many-body / 多体 | Structure / 结构 | `None` |
+| `AtomicComposition` | Local / 局部 | Structure / 结构 | `None` |
+| `NeighborList` | Local / 局部 | Pair / 原子对 | `None` |
+| `SortedDistances` | Local / 局部 | Atom / 原子 | `None` |
+| `SphericalExpansion` | Local / 局部 | Atom / 原子 | `None` |
+| `SphericalExpansionByPair` | Local / 局部 | Pair / 原子对 | `None` |
+| `SoapRadialSpectrum` | Local / 局部 | Atom / 原子 | `None` |
+| `SoapPowerSpectrum` | Local / 局部 | Atom / 原子 | `None` |
+| `LodeSphericalExpansion` | Local / 局部 | Atom / 原子 | `None` |
+| `EAD` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `SO3` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `SO4` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `SNAP` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `LBispectrum` | Rotational / 旋转 | Atom / 原子 | `None` |
+| `MTP` | Local / 局部 | Atom / 原子 | `Optional` |
+| `C00PSMLFF` | Local / 局部 | Atom / 原子 | `None` |
+| `NEP` | Model-backed / 模型 | Atom / 原子 | `Required` |
+| `DPA4` | Model-backed / 模型 | Atom / 原子 | `Required` |
+| `DPA4C` | Model-backed / 模型 | Atom / 原子 | `Required` |
 
 ## Registry / 注册表
 
@@ -146,6 +210,8 @@ import mdescriptor
 from mdescriptor.descriptors import SOAP
 
 print(mdescriptor.list_descriptors())
+metadata = mdescriptor.describe_descriptor("SOAP")
+runtime = mdescriptor.get_runtime_info()
 soap = SOAP(species=[1, 8], r_cut=4.5, n_max=2, l_max=2)
 rebuilt = mdescriptor.create_descriptor(soap.configuration)
 
@@ -156,7 +222,10 @@ child.register(my_spec)
 The built-in list separates `AssetPolicy.NONE`, `OPTIONAL` (for example MTP
 potentials), and `REQUIRED` (NEP/DPA4/DPA4C). The root package exposes stable
 contracts, registry functions and errors only; algorithm implementations are
-not re-exported from the root.
+not re-exported from the root. `describe_descriptor(name)` reads static,
+JSON-safe GUI metadata from the registry without constructing a descriptor or
+resolving a model. `get_runtime_info()` reports the package and contract
+schema versions, including `result_schema_version`.
 
 ## Model resources / 模型资源
 
@@ -175,7 +244,11 @@ dpa4 = DPA4(
 result = dpa4.compute(batch)
 ```
 
-The DPA4/DPA4C checkpoint readers and NumPy reference path remain isolated
+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 fallback path remain isolated
 vendor adapters. The default inference graphs are lowered into the private
 `mdescriptor._native` C++17/OpenMP extension.
 
@@ -184,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.2 → 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.2 → mdescriptor-0.2.4}/cpp/src/common/control.cpp

@@ -1,8 +1,13 @@
 #include "mdescriptor/descriptor.hpp"
 
+#include <stdexcept>
+
 namespace mdescriptor {
 
 void ComputeControl::reset(std::int64_t total) {
+    if (total < 0) {
+        throw std::invalid_argument("control total must be non-negative");
+    }
     cancelled_.store(false, std::memory_order_release);
     completed_.store(0, std::memory_order_release);
     total_.store(total, std::memory_order_release);

{mdescriptor-0.2.2 → mdescriptor-0.2.4}/cpp/src/common/nep.cpp

@@ -693,6 +693,9 @@ void compute_nep(
     int num_threads,
     double* output,
     const std::shared_ptr<ComputeControl>& control) {
+    if (control) {
+        control->reset(batch.structures);
+    }
     const std::size_t radial_basis = static_cast<std::size_t>(model.basis_size_radial + 1);
     const std::size_t angular_basis = static_cast<std::size_t>(model.basis_size_angular + 1);
     const std::size_t radial_n = static_cast<std::size_t>(model.n_max_radial + 1);
@@ -858,6 +861,9 @@ void compute_nep(
         for (std::int64_t structure = 0; structure < batch.structures; ++structure) {
             if (control && control->cancelled()) break;
             compute_structure(structure, radial, sums, angular, basis);
+            if (control && !control->cancelled()) {
+                control->mark_completed();
+            }
         }
         if (control && control->cancelled()) throw CancelledError();
         return;
@@ -883,6 +889,9 @@ void compute_nep(
                 if (control && control->cancelled()) continue;
                 try {
                     compute_structure(structure, radial, sums, angular, basis);
+                    if (control && !control->cancelled()) {
+                        control->mark_completed();
+                    }
                 } catch (...) {
                     record_error(std::current_exception());
                 }
@@ -897,6 +906,9 @@ void compute_nep(
             if (control && control->cancelled()) break;
             try {
                 compute_structure(structure, radial, sums, angular, basis);
+                if (control && !control->cancelled()) {
+                    control->mark_completed();
+                }
             } catch (...) {
                 record_error(std::current_exception());
                 break;
@@ -935,6 +947,9 @@ void compute_nep(
     }
 #endif
     if (control && control->cancelled()) throw CancelledError();
+    if (control) {
+        control->mark_completed();
+    }
 }
 
 NepCalculator::NepCalculator(NepOptions options)

{mdescriptor-0.2.2 → mdescriptor-0.2.4}/cpp/src/standalone/ace.cpp

@@ -805,6 +805,7 @@ void AceCalculator::compute(
     const std::shared_ptr<ComputeControl>& control) const {
     if (closed()) throw std::runtime_error("ACE calculator is closed");
     std::lock_guard<std::mutex> lock(compute_mutex_);
+    if (control) control->reset(batch.structures);
     const auto graph = build_neighbor_graph(batch, options_.r_cut, control, options_.num_threads);
     std::map<std::int32_t, int> species_index;
     for (std::size_t i = 0; i < options_.species.size(); ++i) {

{mdescriptor-0.2.2 → 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.2 → mdescriptor-0.2.4}/cpp/src/standalone/mtp.cpp

@@ -752,6 +752,9 @@ void MtpCalculator::compute(
         throw std::runtime_error("MTP calculator is closed");
     }
     std::lock_guard<std::mutex> lock(compute_mutex_);
+    if (control) {
+        control->reset(batch.structures);
+    }
     if (official_model_) {
         if (official_model_->native_mlip4) {
             official_model_->native_model->compute(batch, options_.species, options_.num_threads, output, control);

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)