MDescriptor

MDescriptor is a batch-oriented periodic atomic-descriptor library. The numerical kernels are implemented in C++17 and all Python descriptors share one input/result/lifecycle contract.

MDescriptor 是面向批量周期结构的原子描述符库。数值核心使用 C++17；所有 Python 描述符共享统一的输入、结果和生命周期契约。

Layout / 布局

The public namespace is intentionally small:

src/mdescriptor/             installable package
src/mdescriptor/core/         Descriptor, StructureBatch, DescriptorResult
src/mdescriptor/descriptors/
  standalone/                 no model required (ACE, matrices/, many_body/, local/, rotational/)
  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 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 always resolve a model resource (a packaged default or an explicit model= path). There are no network downloads or implicit model discovery.

standalone 中的描述符不需要模型文件；model_backed 中的 NEP、DPA4、DPA4C 始终解析模型资源（内置默认模型或显式 model= 路径）。不会联网下载，也不会扫描目录自动发现模型。

Installation / 安装

The base package requires Python 3.10+, NumPy and array-api-compat. ASE is optional and is only needed for StructureBatch.from_ase or direct ASE input. GUI/native frame records can use StructureBatch.from_frames without ASE. Sparse output is provided as SciPy CSR by the optional sparse extra.

基础包需要 Python 3.10+、NumPy 和 array-api-compat。ASE 只在使用 StructureBatch.from_ase 或直接传入 ASE 对象时需要；稀疏输出由可选的 sparse extra 提供。GUI/原生帧记录可使用 StructureBatch.from_frames，不依赖 ASE。

python -m pip install .
python -m pip install ".[ase]"
python -m pip install ".[sparse]"

DPA4 and DPA4C are CPU-only implementations. Their official .pt checkpoints are parsed by the bundled restricted NumPy reader without importing or 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.

All built-in descriptors currently advertise and execute on CPU only. CUDA/GPU execution is not available in this release; execution.device="cuda" is rejected rather than silently falling back. Adding GPU support requires a device-specific kernel and a corresponding wheel/runtime build.

可选的外部数值对照固定使用 deepmd-kit==3.2.0：

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 个描述符都登记在数值基线清单，并都有外部静态 golden：7 个沿用独立上游/source NPZ，另外 21 个在对应目录的 external_manifest.json 中保存固定版本 provider 生成的数值。默认测试只依赖提交的 fixture；外部 provider 缺失或版本漂移会使 reference job 失败，而不会静默跳过。

性能说明：DPA4 native 路径现在使用固定大小分块的 SGEMM、可复用的计算工作区，并只为每条边计算一次 attention logit；DPA4C 的类型对 MLP 采用每个 calculator 实例独立的惰性缓存。OpenBLAS 仅作为构建依赖，官方 wheel 会内置 prefixed 的 OpenBLAS 及其运行时闭包和许可文件，安装后不需要 scipy-openblas32、Torch 或其他新增运行时依赖。大批量独立结构按结构分块消费，以控制峰值内存。

本地可复现实测（脚本默认 2 次预热、5 次稳态；基线为提交 334e159）可用以下命令生成完整 JSON 报告；报告同时记录构造、首次调用、p95、线程扫描、RSS 和 profiling 构建中的私有阶段计时：

python scripts/benchmark_dpa_native.py \
  --descriptor DPA4 --dataset carbon_dataset_pbc --limit-frames 50 \
  --threads 1,4,32 --output /tmp/dpa4-native.json

当前 Linux 主机的候选测量中，DPA4 的 41 原子小批 median 约为 0.47 s（1 线程）和 0.30 s（32 线程）；50 帧/3200 原子单次吞吐约为 57.8 s（1 线程）和 21.6 s（32 线程）。这些数字用于同机 A/B 门禁，不代表跨机器性能保证。

Input contract / 输入契约

import numpy as np
from mdescriptor import StructureBatch

batch = StructureBatch(
    numbers=np.array([1, 8], dtype=np.int32),
    positions=np.array([[0., 0., 0.], [1., 0., 0.]]),
    cells=np.eye(3, dtype=np.float64)[None] * 12,
    pbc=np.ones((1, 3), dtype=np.int32),
    offsets=np.array([0, 2], dtype=np.int64),
    ids=("water-0",),
)

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(...); GUI-style mappings or objects exposing numbers, positions, cell, pbc and id can use StructureBatch.from_frames(...).

Descriptor API / 描述符 API

Algorithm classes live under mdescriptor.descriptors and use canonical names:

from mdescriptor.descriptors import SOAP

soap = SOAP(species=[1, 8], r_cut=4.5, n_max=4, l_max=3, average="off")
result = soap.compute(batch)

assert result.level == "atom"
assert result.values.shape == (batch.atoms, soap.feature_count)
assert len(result.labels) == result.values.shape[1]

with SOAP(species=[1, 8], r_cut=4.5, n_max=2, l_max=2) as descriptor:
    result = descriptor.compute(batch)

ACE (Atomic Cluster Expansion) is available as a standalone atom-level descriptor. Its public options mirror the standard ACE1.jl Utils.rpi_basis path and accept atomic numbers or chemical symbols:

from mdescriptor.descriptors import ACE

ace = ACE(species=["H", "O"], N=3, maxdeg=8, rcut=5.0)
result = ace.compute(batch)

Every descriptor has idempotent close(), a closed property and synchronous context-manager support. Computing after close raises ClosedDescriptorError. Instances are synchronous and not promised to be thread-safe.

每个描述符都提供幂等 close()、closed 属性和同步上下文管理器；关闭后计算会抛出 ClosedDescriptorError。实例是同步的，不承诺线程安全。

DescriptorResult contains values, level (atom, structure, or pair), 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. 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 for parameters, capabilities and backend details.

内置注册表目前提供 28 个描述符。None 表示不需要模型文件；Optional 表示可以提供模型（例如 MTP）；Required 表示描述符始终解析本地模型资源。参数、能力和后端详情请参阅完整描述符清单。

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 / 注册表

Built-ins come from one explicit immutable specification list. Imports are lazy and no decorator or filesystem scan is used.

import mdescriptor
from mdescriptor.descriptors import SOAP

print(mdescriptor.list_descriptors())
summaries = mdescriptor.list_descriptors(detailed=True)
metadata = mdescriptor.describe_descriptor("SOAP")
runtime = mdescriptor.get_runtime_info()
baseline = mdescriptor.gui_baseline()
soap = SOAP(species=[1, 8], r_cut=4.5, n_max=2, l_max=2)
rebuilt = mdescriptor.create_descriptor(soap.configuration)

child = mdescriptor.DescriptorRegistry(parent=mdescriptor.builtin_registry)
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. describe_descriptor(name) reads static, JSON-safe GUI metadata from the registry without constructing a descriptor or resolving a model. list_descriptors(detailed=True) returns the name, version, display name, category and level for every descriptor in one call. gui_baseline() returns the packaged GUI contract document, and get_runtime_info() reports its baseline_version alongside the package and schema versions.

The keys in metadata["parameters"] are the unchanged constructor and configuration names. Each parameter schema also contains a GUI-facing display_name and description; use the former as the field label and the latter as the tooltip, while submitting the value under the mapping key:

metadata = mdescriptor.describe_descriptor("SOAP")
for parameter_name, schema in metadata["parameters"].items():
    label = schema["display_name"]
    tooltip = schema["description"]
    # Render `label` and `tooltip`, then serialize the value as `parameter_name`.

On Windows, import mdescriptor during single-threaded startup, before an embedding host starts background stdin/stdio readers. The package preloads the packaged native binary at that point; a host that controls startup explicitly may also call mdescriptor.preload_native().

Model resources / 模型资源

ModelResource, ModelResolver, LoadedModel and ModelSession are the shared model-resource seam. Resolution is explicit, local and checksum-aware:

from pathlib import Path
from mdescriptor.descriptors import DPA4
from mdescriptor import ExecutionOptions

dpa4 = DPA4(
    model=Path("/path/to/official-checkpoint.pt"),
    execution=ExecutionOptions(device="cpu"),
)
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 fallback path remain isolated vendor adapters. The default inference graphs are lowered into the private mdescriptor._native C++17/OpenMP extension.

Development / 开发

.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 is licensed under the GNU General Public License v3.0; see LICENSE.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mdescriptor-0.2.7.tar.gz (26.4 MB view details)

Uploaded Aug 29, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

mdescriptor-0.2.7-cp314-cp314-win_amd64.whl (33.8 MB view details)

Uploaded Aug 29, 2026 CPython 3.14Windows x86-64

mdescriptor-0.2.7-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (35.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.14manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mdescriptor-0.2.7-cp314-cp314-macosx_11_0_arm64.whl (33.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.14macOS 11.0+ ARM64

mdescriptor-0.2.7-cp313-cp313-win_amd64.whl (33.6 MB view details)

Uploaded Aug 29, 2026 CPython 3.13Windows x86-64

mdescriptor-0.2.7-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (35.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mdescriptor-0.2.7-cp313-cp313-macosx_11_0_arm64.whl (33.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.13macOS 11.0+ ARM64

mdescriptor-0.2.7-cp312-cp312-win_amd64.whl (33.6 MB view details)

Uploaded Aug 29, 2026 CPython 3.12Windows x86-64

mdescriptor-0.2.7-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (35.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.12manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mdescriptor-0.2.7-cp312-cp312-macosx_11_0_arm64.whl (33.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.12macOS 11.0+ ARM64

mdescriptor-0.2.7-cp311-cp311-win_amd64.whl (33.6 MB view details)

Uploaded Aug 29, 2026 CPython 3.11Windows x86-64

mdescriptor-0.2.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (35.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.11manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mdescriptor-0.2.7-cp311-cp311-macosx_11_0_arm64.whl (33.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.11macOS 11.0+ ARM64

mdescriptor-0.2.7-cp310-cp310-win_amd64.whl (33.6 MB view details)

Uploaded Aug 29, 2026 CPython 3.10Windows x86-64

mdescriptor-0.2.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (35.4 MB view details)

Uploaded Aug 29, 2026 CPython 3.10manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

mdescriptor-0.2.7-cp310-cp310-macosx_11_0_arm64.whl (33.2 MB view details)

Uploaded Aug 29, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file mdescriptor-0.2.7.tar.gz.

File metadata

Download URL: mdescriptor-0.2.7.tar.gz
Upload date: Aug 29, 2026
Size: 26.4 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for mdescriptor-0.2.7.tar.gz
Algorithm	Hash digest
SHA256	`c1a30f75f809d0a28855d26df1f7ad0e1b93fd7b2f149ab40900f2052c49b98e`
MD5	`ff030e480e9a8c8a9425ccda17cc6026`
BLAKE2b-256	`ac5f35a5f15723b1fa8e2d622a59f15cfd6f3af617be4b6cbba75d6ecd123172`

Algorithm	Hash digest
SHA256	`dc046f459e0583992701bb305c3394a3417e64dbb921575e173ecbf9e784d508`
MD5	`60ecd171ea52324dc71b098c7cee35d4`
BLAKE2b-256	`f8bc652ebbf7d3575142f35fb29fb2d2dd8806a11f703c1d7356e2c786b32152`

Algorithm	Hash digest
SHA256	`b1d88d711775bbc0cbe9391dabb1b11ddceee5189bd3c9f7bbccaf6487fdfce8`
MD5	`1a6415e23c3d3305c54cb29a80ad4011`
BLAKE2b-256	`6789e409e007258b0ace4bcade3e355d9346358a271235ef31c42b1366b244df`

Algorithm	Hash digest
SHA256	`8978e651ab410bc2b9d181be8dfa169d962bb4b67a4198500d36d68faec6fde8`
MD5	`259139ed7ecbe082196bf3827c69b051`
BLAKE2b-256	`ff49379b9b78d48a5ffa93b200da6399f2b9c507e34793ec8a3f0cfaac843094`

Algorithm	Hash digest
SHA256	`e1be955deaec6bad3b04aab881784f929c850ef089dec151050666a209c9ab61`
MD5	`f32562a95682b22f51d77f48aca7d0cd`
BLAKE2b-256	`d5549e750d0089285fa2291196be1e51e2888961fca36787d835397422d29210`

Algorithm	Hash digest
SHA256	`5e6a381bef60cc0b0671b8d3c93b27ae13473d1a66c902e35e2edb1db90124c1`
MD5	`9db5cd20f736522c4cab78433697c297`
BLAKE2b-256	`b62092392a13134d7183065dee013ac9a2db76dd178f0eb1e00ff9f7e786983e`

Algorithm	Hash digest
SHA256	`8a882edcde443cb84a09561c0a700b84a535d8d852ce245611838a1e4607a460`
MD5	`ea05f84d0eaf36c2f70af08afaee9850`
BLAKE2b-256	`e8147cf38e5f2c0fd6999ebe2a5919178ee04b0caf3a2ae0db719da4cc735d7f`

Algorithm	Hash digest
SHA256	`b7cfdcb55d8f16afef9e74dcdbe62c85342838a410d261156f36fd89a6c31a84`
MD5	`994504cdb69eed74aa62902033a90af0`
BLAKE2b-256	`981d3bcc789849116289d80073b324d7dc6674b4c2c9694974da99d6e62cfe64`

Algorithm	Hash digest
SHA256	`cecd29b87c8a1c24d6eabc172ac7ccae97f22bf63f79bb52c90c9a924c8fa468`
MD5	`8ec451e746ab23605615e2a8c510d8ce`
BLAKE2b-256	`8f940945134e1861f4a9f9faefda0aafacaafb966b270c7314af582cc07b978c`

Algorithm	Hash digest
SHA256	`fc9ab0359394842c042158b5b70907aa9c054590e5a7710100c01509d4a84e40`
MD5	`f75a87e4e6169b15a2f30dbc1894be2b`
BLAKE2b-256	`089384990f09815cadc92b61716630fd7b1dc9fab5c30cc71ea95551bbd9f21f`

Algorithm	Hash digest
SHA256	`c789bdd102e034418567bd8d801d2cbefb22829b56d72c7c388644aa070aa043`
MD5	`b894d767aa1e73001a131762b65ccad8`
BLAKE2b-256	`0d9597b3b53facb21b0bf8c1a8fc6d22321c3785da2ac2a67b529dccd4d9533c`

Algorithm	Hash digest
SHA256	`0f1304f277b7206fca9d6252b3d1f188e3f7e7fe89fd4bb371af3f82bba105b9`
MD5	`63401e0a593184667f023a24a12f9912`
BLAKE2b-256	`47047b44ea691a26d646a3712e3b8a68f76ab3178dad10c444d90904d7c6ae9a`

Algorithm	Hash digest
SHA256	`a0b7b2cf19c4b81cd6e7b771c201840b647af3b9bc65b80357bb46b195a4c301`
MD5	`25cbf98ca23eeeec175195d57e8c4aa3`
BLAKE2b-256	`a68c24d727809ed36e510a50531be009751d4bd1a99aac839a91e1174fd9c195`

Algorithm	Hash digest
SHA256	`e9536062e11edb646de46ce951b7a2fa713d65a5111992478641a526cec68572`
MD5	`d60f9e12bcbbe1f925ec3ae4eea2716a`
BLAKE2b-256	`54d3dfe58edd03eaa8e613154806bf17912cce6851a51196b1fe5ed16c25f159`

Algorithm	Hash digest
SHA256	`2d9e2219e3b5e59ceb1d871afb642900230daa701b3bba568e22b03c5fdc26e3`
MD5	`3c75c13e40883fc77589fc03e57428bd`
BLAKE2b-256	`318a0ecdad6e33dc43234cc4b9c92dfd797d43904970c4ce2b60817f068dc060`

Algorithm	Hash digest
SHA256	`2ad436067b22389f77d54a0e330df871e1d12440b2705a42864081b26349b7d5`
MD5	`3b22a38bb62979764b2d0af8b8b5e87a`
BLAKE2b-256	`e96144e00479350da124d4d79e4a67161cd8df0d040a9f7a59f5ce29c4c54172`

MDescriptor 0.2.7

MDescriptor

Layout / 布局

Installation / 安装

Input contract / 输入契约

Descriptor API / 描述符 API

Supported descriptors / 支持的描述符

Registry / 注册表

Model resources / 模型资源

Development / 开发

Key dates

1 maintainer

License

Requires

Provides Extra

Download files

Source Distribution

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata