MDescriptor 0.2.2__tar.gz → 0.2.3__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: MDescriptor
-Version: 0.2.2
+Version: 0.2.3
 Summary: Batch-oriented periodic atomic descriptors with C++17 kernels
 License:                     GNU GENERAL PUBLIC LICENSE
                                 Version 3, 29 June 2007
@@ -689,11 +689,32 @@ Provides-Extra: test
 Requires-Dist: pytest>=8; 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"
@@ -796,7 +817,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 +863,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 +919,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 +931,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,6 +953,10 @@ dpa4 = DPA4(
 result = dpa4.compute(batch)
 ```
 
+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
 vendor adapters. The default inference graphs are lowered into the private
 `mdescriptor._native` C++17/OpenMP extension.

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

@@ -89,7 +89,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 +135,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 +191,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 +203,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,6 +225,10 @@ dpa4 = DPA4(
 result = dpa4.compute(batch)
 ```
 
+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
 vendor adapters. The default inference graphs are lowered into the private
 `mdescriptor._native` C++17/OpenMP extension.

{mdescriptor-0.2.2 → mdescriptor-0.2.3}/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.3}/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.3}/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.3}/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.3/docs/descriptor-inventory.md

@@ -0,0 +1,110 @@
+# Descriptor inventory / 描述符清单
+
+This page is generated from the immutable built-in registry.  It is a
+controlled artifact: run `python scripts/check_descriptor_inventory.py
+--write` when a registry spec changes, and keep the `--check` gate in CI.
+
+<!-- registry-names: SOAP, SOAPTurbo, ACSF, ACE, CoulombMatrix, SineMatrix, EwaldSumMatrix, MBTR, LMBTR, ValleOganov, AtomicComposition, NeighborList, SortedDistances, SphericalExpansion, SphericalExpansionByPair, SoapRadialSpectrum, SoapPowerSpectrum, LodeSphericalExpansion, EAD, SO3, SO4, SNAP, LBispectrum, MTP, C00PSMLFF, NEP, DPA4, DPA4C -->
+
+| Name | Directory group | Category | Asset policy | Backend | Level | Capabilities | Parameters | Extra |
+|---|---|---|---|---|---|---|---|---|
+| SOAP | `standalone` | `local` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | species, rbf, n_max, l_max, sigma, average, weighting, r_cut, compression | `—` |
+| SOAPTurbo | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, alpha_max, l_max, rcut_hard, rcut_soft, nf, radial_enhancement, basis, compression, atom_sigma_r, atom_sigma_r_scaling, atom_sigma_t, atom_sigma_t_scaling, amplitude_scaling, central_weight, central_species | `—` |
+| ACSF | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, r_cut, g2_params, g3_params, g4_params, g5_params | `—` |
+| ACE | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, N, r0, trans, wL, maxdeg, D, rcut, rin, pcut, pin, constants | `—` |
+| CoulombMatrix | `standalone` | `matrix` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | n_atoms_max, permutation, exponent | `—` |
+| SineMatrix | `standalone` | `matrix` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | n_atoms_max, permutation, exponent | `—` |
+| EwaldSumMatrix | `standalone` | `matrix` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | n_atoms_max, permutation, accuracy, w, r_cut, g_cut, a | `—` |
+| MBTR | `standalone` | `many_body` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | species, geometry, grid, weighting, periodic, normalize_gaussians, normalization | `—` |
+| LMBTR | `standalone` | `many_body` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, geometry, grid, weighting, periodic, normalize_gaussians, normalization | `—` |
+| ValleOganov | `standalone` | `many_body` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | species, function, n, sigma, r_cut, geometry, grid, weighting, periodic, normalize_gaussians, normalization | `—` |
+| AtomicComposition | `standalone` | `local` | `NONE` | `cpp` | `structure` | cooperative_cancel, num_threads, sparse | species, per_system | `—` |
+| NeighborList | `standalone` | `local` | `NONE` | `cpp` | `pair` | cooperative_cancel, num_threads, sparse | cutoff, full_neighbor_list, self_pairs | `—` |
+| SortedDistances | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, cutoff, max_neighbors, separate_neighbor_types | `—` |
+| SphericalExpansion | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, cutoff, density_width, max_radial, max_angular | `—` |
+| SphericalExpansionByPair | `standalone` | `local` | `NONE` | `cpp` | `pair` | cooperative_cancel, num_threads, sparse | species, cutoff, density_width, max_radial, max_angular | `—` |
+| SoapRadialSpectrum | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, cutoff, density_width, max_radial, max_angular | `—` |
+| SoapPowerSpectrum | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, cutoff, density_width, max_radial, max_angular | `—` |
+| LodeSphericalExpansion | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, cutoff, density_width, max_radial, max_angular, k_cutoff, exponent, radial_radius | `—` |
+| EAD | `standalone` | `rotational` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | parameters, Rc, cutoff | `—` |
+| SO3 | `standalone` | `rotational` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | nmax, lmax, rcut, alpha, weight_on | `—` |
+| SO4 | `standalone` | `rotational` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | lmax, rcut, normalize_U | `—` |
+| SNAP | `standalone` | `rotational` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | weights, lmax, rcut, normalize_U | `—` |
+| LBispectrum | `standalone` | `rotational` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | twojmax, diagonal, rfac0, rmin0, rcutfac, element_profile, element_radii, weights, rcut, normalize_U | `—` |
+| MTP | `standalone` | `local` | `OPTIONAL` | `cpp` | `atom` | cooperative_cancel, model, num_threads, sparse | species, model, min_dist, max_dist, r_cut, radial_basis_size, radial_funcs_count, max_rank, radial_basis_type | `—` |
+| C00PSMLFF | `standalone` | `local` | `NONE` | `cpp` | `atom` | cooperative_cancel, num_threads, sparse | species, r_cut, n_radial, l_max, cutoff_function, radial_sigma, include_radial, include_angular, normalize_radial, normalize_angular, super_vector, radial_weight, angular_weight, exclude_self_interaction | `—` |
+| NEP | `model_backed` | `model_backed` | `REQUIRED` | `cpp` | `atom` | cooperative_cancel, model, num_threads, sparse | model | `—` |
+| DPA4 | `model_backed` | `model_backed` | `REQUIRED` | `numpy` | `atom` | charge_spin, model, num_threads, sparse, spin | model | `—` |
+| DPA4C | `model_backed` | `model_backed` | `REQUIRED` | `numpy` | `atom` | charge_spin, model, num_threads, sparse, spin | model, calibrate | `—` |
+
+## Static descriptor metadata
+
+Each built-in entry carries `DescriptorInfo` schema version
+`1`.  Query it without importing an algorithm
+implementation or resolving a model:
+
+```python
+import mdescriptor
+
+metadata = mdescriptor.describe_descriptor("SOAP")
+```
+
+The returned object is JSON-safe and contains the canonical parameter schema,
+execution devices, input periodicity, output representation, and model asset
+policy.  Historical Python constructor aliases remain available to direct
+callers but are intentionally omitted from the canonical GUI parameter list.
+
+The canonical algorithm imports are:
+
+```python
+from mdescriptor.descriptors import SOAP, ACSF, ACE, MTP, NEP, DPA4, DPA4C
+```
+
+The root package exposes contracts, registry queries and the configuration
+factory.  Algorithm classes are deliberately not re-exported from the root.
+
+## Backend boundaries
+
+- C++17/OpenMP kernels implement the standalone numerical formulas.
+- `mdescriptor._native` is the private pybind11 extension name.
+- Python adapters own input packing, lifecycle, typed options and result
+  normalization.
+- DPA4/DPA4C use the bundled NumPy checkpoint loader and fallback inference
+  core; supported default graphs are executed by C++17/OpenMP, and official
+  ``.pt`` files are parsed without importing Torch.
+- NEP, DPA4 and DPA4C model files are resolved locally and verified by
+  streaming SHA-256 before loading.
+
+## Result contract
+
+Every public class returns `DescriptorResult` from `compute(...)`.  Values are
+two-dimensional and `samples` is a contiguous `int64` array with the fixed
+shape `[structure]`, `[structure, local_atom]`, or
+`[structure, local_atom_1, local_atom_2, shift_a, shift_b, shift_c]` according
+to the output level.  Metadata uses the versioned JSON-safe schema; descriptors
+retain configuration and metadata after `close()`.
+
+Common representation and execution settings are passed as
+`OutputOptions`/`ExecutionOptions`.  Sparse output is SciPy CSR and fails at
+construction when the optional dependency is unavailable.
+
+## Optional dependencies
+
+The base import and DPA4/DPA4C computation do not import Torch.  Install
+`.[ase]` for ASE input conversion and `.[sparse]` for SciPy CSR output.
+Official `.pt` loads use the package's restricted NumPy checkpoint reader;
+network downloads are not implemented.
+
+## Native source map
+
+| Family | Source |
+|---|---|
+| SOAP / ACSF / ACE / SOAPTurbo | `cpp/src/standalone/soap.cpp`, `acsf.cpp`, `ace.cpp`, `soap_turbo.cpp` |
+| matrices / MBTR | `cpp/src/standalone/*_matrix.cpp`, `matrix_dispatch.cpp`, `mbtr.cpp` |
+| local descriptors | `cpp/src/standalone/atomic_composition.cpp`, `neighbor_list.cpp`, `sorted_distances.cpp`, `spherical_expansion*.cpp` |
+| rotational / MTP / C00PS | `cpp/src/standalone/ead.cpp`, `rotational_descriptors.cpp`, `mtp*.cpp`, `c00ps_mlff.cpp` |
+| NEP | `cpp/src/common/nep.cpp` |
+| shared helpers | `cpp/include/mdescriptor/detail/`, `cpp/src/common/` |
+
+Algorithm numerical behavior is frozen during this layout refactor.  Formula
+changes require a separate reference/golden update.

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

@@ -24,7 +24,27 @@ dependencies = [
 ase = ["ase>=3.22"]
 sparse = ["scipy>=1.11"]
 test = ["pytest>=8", "ase>=3.22", "scipy>=1.11"]
-reference = ["pytest>=8", "ase==3.26.0", "scipy>=1.11", "dscribe==2.1.2"]
+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 = [
+    "pytest>=8",
+    "ase==3.26.0",
+    "scipy>=1.11",
+    "numba>=0.50.1",
+    "pyxtal_ff==0.2.3",
+]
+reference-deepmd = [
+    "pytest>=8",
+    "ase==3.26.0",
+    "scipy>=1.11",
+    "deepmd-kit[torch]==3.2.0",
+]
+reference-nepadapters = [
+    "pytest>=8",
+    "ase==3.26.0",
+    "scipy>=1.11",
+    "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"]
 
@@ -77,7 +97,12 @@ testpaths = ["tests"]
 addopts = "-m 'not reference'"
 markers = [
     "model: tests that exercise bundled model-backed descriptors and assets",
-    "reference: tests that require the pinned external numerical reference stack",
+    "reference: tests that require a pinned external numerical reference implementation",
+    "dscribe: external numerical comparisons against pinned DScribe",
+    "featomic: external numerical comparisons against pinned Featomic",
+    "pyxtalff: external numerical comparisons against pinned PyXtal_FF descriptors",
+    "deepmd: external numerical comparisons against pinned deepmd-kit DPA4 descriptors",
+    "nepadapters: external numerical comparisons against pinned nep-adapters",
 ]
 
 [tool.ruff]
@@ -97,7 +122,7 @@ ignore = ["E501"]
 # the interpreter used for the quality gate; the package itself still supports
 # CPython 3.10 at runtime.
 python_version = "3.12"
-files = ["src/mdescriptor/core", "src/mdescriptor/registry", "src/mdescriptor/models"]
+files = ["src/mdescriptor"]
 check_untyped_defs = true
 disallow_any_generics = false
 no_implicit_optional = true

{mdescriptor-0.2.2 → mdescriptor-0.2.3}/scripts/check_descriptor_inventory.py

@@ -12,7 +12,11 @@ import argparse
 import re
 from pathlib import Path
 
-from mdescriptor import builtin_registry, list_descriptors
+from mdescriptor import (
+    DESCRIPTOR_INFO_SCHEMA_VERSION,
+    builtin_registry,
+    list_descriptors,
+)
 
 ROOT = Path(__file__).resolve().parents[1]
 DOC = ROOT / "docs" / "descriptor-inventory.md"
@@ -26,9 +30,15 @@ def render() -> str:
         group = "standalone" if ".standalone." in spec.import_path else "model_backed"
         capabilities = ", ".join(sorted(spec.capabilities)) or "—"
         extra = spec.optional_extra or "—"
+        category = "—" if spec.info is None else spec.info.category
+        parameters = (
+            "—"
+            if spec.info is None or not spec.info.parameters
+            else ", ".join(spec.info.parameters)
+        )
         rows.append(
-            f"| {spec.name} | `{group}` | `{spec.asset_policy.value.upper()}` | "
-            f"`{spec.backend}` | `{spec.level}` | {capabilities} | `{extra}` |"
+            f"| {spec.name} | `{group}` | `{category}` | `{spec.asset_policy.value.upper()}` | "
+            f"`{spec.backend}` | `{spec.level}` | {capabilities} | {parameters} | `{extra}` |"
         )
     return """# Descriptor inventory / 描述符清单
 
@@ -38,10 +48,27 @@ controlled artifact: run `python scripts/check_descriptor_inventory.py
 
 <!-- registry-names: {names} -->
 
-| Name | Directory group | Asset policy | Backend | Level | Capabilities | Extra |
-|---|---|---|---|---|---|---|
+| Name | Directory group | Category | Asset policy | Backend | Level | Capabilities | Parameters | Extra |
+|---|---|---|---|---|---|---|---|---|
 {rows}
 
+## Static descriptor metadata
+
+Each built-in entry carries `DescriptorInfo` schema version
+`{DESCRIPTOR_INFO_SCHEMA_VERSION}`.  Query it without importing an algorithm
+implementation or resolving a model:
+
+```python
+import mdescriptor
+
+metadata = mdescriptor.describe_descriptor("SOAP")
+```
+
+The returned object is JSON-safe and contains the canonical parameter schema,
+execution devices, input periodicity, output representation, and model asset
+policy.  Historical Python constructor aliases remain available to direct
+callers but are intentionally omitted from the canonical GUI parameter list.
+
 The canonical algorithm imports are:
 
 ```python
@@ -96,7 +123,11 @@ network downloads are not implemented.
 
 Algorithm numerical behavior is frozen during this layout refactor.  Formula
 changes require a separate reference/golden update.
-""".format(names=names, rows="\n".join(rows)).rstrip() + "\n"
+""".format(
+        names=names,
+        rows="\n".join(rows),
+        DESCRIPTOR_INFO_SCHEMA_VERSION=DESCRIPTOR_INFO_SCHEMA_VERSION,
+    ).rstrip() + "\n"
 
 
 def main(argv: list[str] | None = None) -> int:

mdescriptor-0.2.3/src/mdescriptor/__init__.py

@@ -0,0 +1,89 @@
+"""Stable MDescriptor contracts and explicit registry functions."""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+
+from .core import (
+    CONFIGURATION_SCHEMA_VERSION,
+    RESULT_SCHEMA_VERSION,
+    CancelledError,
+    ClosedDescriptorError,
+    ComputeControl,
+    Descriptor,
+    DescriptorConfigError,
+    DescriptorInputError,
+    DescriptorLevel,
+    DescriptorResult,
+    ExecutionOptions,
+    MDescriptorError,
+    ModelLoadError,
+    OutputOptions,
+    StructureBatch,
+    StructureInput,
+)
+from .registry import (
+    DESCRIPTOR_INFO_SCHEMA_VERSION,
+    AssetPolicy,
+    DescriptorConfiguration,
+    DescriptorRegistry,
+    DescriptorSpec,
+    builtin_registry,
+    create_descriptor,
+    describe_descriptor,
+    get_descriptor,
+    list_descriptors,
+)
+
+API_VERSION = 1
+
+try:
+    from ._version import __version__
+except ImportError:  # pragma: no cover - source tree without generated version
+    try:
+        __version__ = package_version("MDescriptor")
+    except PackageNotFoundError:  # pragma: no cover - uninstalled source tree
+        __version__ = "0+unknown"
+
+
+def get_runtime_info() -> dict[str, str | int]:
+    """Return package and public schema versions for backend run metadata."""
+
+    return {
+        "version": __version__,
+        "api_version": API_VERSION,
+        "configuration_schema_version": CONFIGURATION_SCHEMA_VERSION,
+        "descriptor_info_schema_version": DESCRIPTOR_INFO_SCHEMA_VERSION,
+        "result_schema_version": RESULT_SCHEMA_VERSION,
+    }
+
+__all__ = [
+    "API_VERSION",
+    "AssetPolicy",
+    "CancelledError",
+    "ClosedDescriptorError",
+    "ComputeControl",
+    "Descriptor",
+    "DescriptorConfigError",
+    "DescriptorConfiguration",
+    "DescriptorInputError",
+    "DescriptorLevel",
+    "DescriptorRegistry",
+    "DescriptorResult",
+    "DescriptorSpec",
+    "DESCRIPTOR_INFO_SCHEMA_VERSION",
+    "CONFIGURATION_SCHEMA_VERSION",
+    "ExecutionOptions",
+    "MDescriptorError",
+    "ModelLoadError",
+    "OutputOptions",
+    "RESULT_SCHEMA_VERSION",
+    "StructureBatch",
+    "StructureInput",
+    "builtin_registry",
+    "create_descriptor",
+    "describe_descriptor",
+    "get_descriptor",
+    "get_runtime_info",
+    "list_descriptors",
+    "__version__",
+]

{mdescriptor-0.2.2 → mdescriptor-0.2.3}/src/mdescriptor/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.2'
-__version_tuple__ = version_tuple = (0, 2, 2)
+__version__ = version = '0.2.3'
+__version_tuple__ = version_tuple = (0, 2, 3)
 
-__commit_id__ = commit_id = 'g008362543'
+__commit_id__ = commit_id = 'gca2e8c11b'