MDescriptor 0.2.4__tar.gz → 0.2.6__tar.gz

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/CMakeLists.txt

@@ -186,6 +186,8 @@ install(FILES "${SCIPY_OPENBLAS_METADATA}"
 install(FILES "${SCIPY_OPENBLAS_LICENSE}"
     DESTINATION mdescriptor/licenses
     RENAME scipy-openblas32-LICENSE.txt)
+install(FILES "${CMAKE_CURRENT_SOURCE_DIR}/docs/gui-adaptation-baseline.md"
+    DESTINATION mdescriptor/docs)
 
 install(
     TARGETS _native

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: MDescriptor
-Version: 0.2.4
+Version: 0.2.6
 Summary: Batch-oriented periodic atomic descriptors with C++17 kernels
 License:                     GNU GENERAL PUBLIC LICENSE
                                 Version 3, 29 June 2007
@@ -767,11 +767,12 @@ path). There are no network downloads or implicit model discovery.
 
 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 提供。
+`sparse` extra 提供。GUI/原生帧记录可使用 `StructureBatch.from_frames`，不依赖 ASE。
 
 ```bash
 python -m pip install .
@@ -785,6 +786,11 @@ 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`：
 
 ```bash
@@ -842,7 +848,9 @@ batch = StructureBatch(
 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(...)`.
+`StructureBatch.from_ase(...)`; GUI-style mappings or objects exposing
+`numbers`, `positions`, `cell`, `pbc` and `id` can use
+`StructureBatch.from_frames(...)`.
 
 ## Descriptor API / 描述符 API
 
@@ -940,8 +948,10 @@ 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)
 
@@ -954,8 +964,16 @@ 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. `get_runtime_info()` reports the package and contract
-schema versions, including `result_schema_version`.
+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.
+
+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 / 模型资源
 

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

@@ -37,11 +37,12 @@ path). There are no network downloads or implicit model discovery.
 
 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 提供。
+`sparse` extra 提供。GUI/原生帧记录可使用 `StructureBatch.from_frames`，不依赖 ASE。
 
 ```bash
 python -m pip install .
@@ -55,6 +56,11 @@ 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`：
 
 ```bash
@@ -112,7 +118,9 @@ batch = StructureBatch(
 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(...)`.
+`StructureBatch.from_ase(...)`; GUI-style mappings or objects exposing
+`numbers`, `positions`, `cell`, `pbc` and `id` can use
+`StructureBatch.from_frames(...)`.
 
 ## Descriptor API / 描述符 API
 
@@ -210,8 +218,10 @@ 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)
 
@@ -224,8 +234,16 @@ 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. `get_runtime_info()` reports the package and contract
-schema versions, including `result_schema_version`.
+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.
+
+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 / 模型资源
 

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/cpp/include/mdescriptor/detail/control.hpp

@@ -45,6 +45,15 @@ inline void mark_completed(const std::shared_ptr<ComputeControl>& control) {
     }
 }
 
+inline void mark_completed_structures(
+    const std::shared_ptr<ComputeControl>& control,
+    std::int64_t structures) {
+    for (std::int64_t structure = 0; structure < structures; ++structure) {
+        check_cancelled(control);
+        mark_completed(control);
+    }
+}
+
 } // namespace detail
 
 } // namespace mdescriptor

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/cpp/src/bindings/module.cpp

@@ -453,8 +453,22 @@ py::array compute_nep_array(
     return output;
 }
 
-py::array compute_dpa4c_array(
-    const Dpa4cCalculator& calculator,
+template <typename Calculator>
+struct DpaBindingTraits;
+
+template <>
+struct DpaBindingTraits<Dpa4cCalculator> {
+    static constexpr const char* name = "DPA4C";
+};
+
+template <>
+struct DpaBindingTraits<Dpa4Calculator> {
+    static constexpr const char* name = "DPA4";
+};
+
+template <typename Calculator>
+py::array compute_dpa_array(
+    const Calculator& calculator,
     const I32Array& numbers,
     const F64Array& positions,
     const F64Array& cells,
@@ -465,30 +479,9 @@ py::array compute_dpa4c_array(
 ) {
     const auto batch = view_batch(numbers, positions, cells, pbc, offsets);
     if (type_indices.ndim() != 1 || type_indices.shape(0) != batch.atoms) {
-        throw std::invalid_argument("DPA4C type_indices must have one entry per atom");
-    }
-    py::array_t<double> output({batch.atoms, calculator.feature_count()});
-    auto ctrl = control_or_default(control);
-    {
-        py::gil_scoped_release release;
-        calculator.compute(batch, type_indices.data(), output.mutable_data(), ctrl);
-    }
-    return output;
-}
-
-py::array compute_dpa4_array(
-    const Dpa4Calculator& calculator,
-    const I32Array& numbers,
-    const F64Array& positions,
-    const F64Array& cells,
-    const I32Array& pbc,
-    const I64Array& offsets,
-    const I32Array& type_indices,
-    const std::shared_ptr<ComputeControl>& control
-) {
-    const auto batch = view_batch(numbers, positions, cells, pbc, offsets);
-    if (type_indices.ndim() != 1 || type_indices.shape(0) != batch.atoms) {
-        throw std::invalid_argument("DPA4 type_indices must have one entry per atom");
+        throw std::invalid_argument(
+            std::string(DpaBindingTraits<Calculator>::name)
+            + " type_indices must have one entry per atom");
     }
     py::array_t<double> output({batch.atoms, calculator.feature_count()});
     auto ctrl = control_or_default(control);
@@ -1117,7 +1110,7 @@ PYBIND11_MODULE(_native, module) {
         .def_property_readonly("feature_count", &Dpa4cCalculator::feature_count)
         .def("close", &Dpa4cCalculator::close)
         .def("closed", &Dpa4cCalculator::closed)
-        .def("compute", &compute_dpa4c_array,
+        .def("compute", &compute_dpa_array<Dpa4cCalculator>,
              py::arg("numbers"), py::arg("positions"), py::arg("cells"), py::arg("pbc"),
              py::arg("offsets"), py::arg("type_indices"), py::arg("control") = nullptr);
 
@@ -1130,7 +1123,7 @@ PYBIND11_MODULE(_native, module) {
         .def_property_readonly("feature_count", &Dpa4Calculator::feature_count)
         .def("close", &Dpa4Calculator::close)
         .def("closed", &Dpa4Calculator::closed)
-        .def("compute", &compute_dpa4_array,
+        .def("compute", &compute_dpa_array<Dpa4Calculator>,
              py::arg("numbers"), py::arg("positions"), py::arg("cells"), py::arg("pbc"),
              py::arg("offsets"), py::arg("type_indices"), py::arg("control") = nullptr);
 

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/cpp/src/model_backed/dpa4.cpp

@@ -2606,6 +2606,7 @@ void Dpa4Calculator::compute(
         }
     }
     if (batch.atoms == 0) {
+        detail::mark_completed_structures(control, batch.structures);
         return;
     }
 
@@ -2751,9 +2752,9 @@ void Dpa4Calculator::compute(
             output[static_cast<std::size_t>(node) * kChannels + static_cast<std::size_t>(channel)] =
                 static_cast<double>(x[index] + output_update[index]);
         }
-        if (control) {
-            control->mark_completed();
-        }
+    }
+    if (control) {
+        control->mark_completed();
     }
     detail::check_cancelled(control);
 }

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/cpp/src/model_backed/dpa4c.cpp

@@ -501,6 +501,7 @@ void Dpa4cCalculator::compute(
         }
     }
     if (batch.atoms == 0) {
+        detail::mark_completed_structures(control, batch.structures);
         return;
     }
 
@@ -540,6 +541,26 @@ void Dpa4cCalculator::compute(
     ensure_pair_cache(used_pair_indices);
 
     const int angular_width = (options_.lmax + 1) * (options_.lmax + 1);
+    std::vector<std::int64_t> structure_for_atom;
+    std::unique_ptr<std::atomic<std::int64_t>[]> remaining_atoms;
+    if (control) {
+        structure_for_atom.resize(static_cast<std::size_t>(batch.atoms));
+        remaining_atoms = std::make_unique<std::atomic<std::int64_t>[]>(
+            static_cast<std::size_t>(batch.structures));
+        for (std::int64_t structure = 0; structure < batch.structures; ++structure) {
+            const std::int64_t begin = batch.offsets[structure];
+            const std::int64_t end = batch.offsets[structure + 1];
+            remaining_atoms[static_cast<std::size_t>(structure)].store(
+                end - begin, std::memory_order_relaxed);
+            for (std::int64_t atom = begin; atom < end; ++atom) {
+                structure_for_atom[static_cast<std::size_t>(atom)] = structure;
+            }
+            if (begin == end) {
+                detail::check_cancelled(control);
+                control->mark_completed();
+            }
+        }
+    }
 #ifdef _OPENMP
 #pragma omp parallel for schedule(static) num_threads(options_.num_threads > 0 ? options_.num_threads : omp_get_max_threads())
 #endif
@@ -915,7 +936,12 @@ void Dpa4cCalculator::compute(
             destination[feature] = value;
         }
         if (control) {
-            control->mark_completed();
+            const std::int64_t structure = structure_for_atom[
+                static_cast<std::size_t>(center_atom)];
+            if (remaining_atoms[static_cast<std::size_t>(structure)].fetch_sub(
+                    1, std::memory_order_acq_rel) == 1) {
+                control->mark_completed();
+            }
         }
     }
     if (control && control->cancelled()) {

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/cpp/src/standalone/ewald_sum_matrix.cpp

@@ -19,6 +19,9 @@ std::vector<double> ewald_matrix_values(
     const std::int64_t begin = batch.offsets[structure];
     const std::int64_t end = batch.offsets[structure + 1];
     const int count = static_cast<int>(end - begin);
+    if (count == 0) {
+        return {};
+    }
 #ifdef _OPENMP
     const int workers = num_threads > 0 ? num_threads : omp_get_max_threads();
 #else

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/docs/descriptor-inventory.md

@@ -34,13 +34,13 @@ controlled artifact: run `python scripts/check_descriptor_inventory.py
 | 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 | `—` |
+| DPA4 | `model_backed` | `model_backed` | `REQUIRED` | `numpy` | `atom` | charge_spin, cooperative_cancel, model, num_threads, sparse, spin | model | `—` |
+| DPA4C | `model_backed` | `model_backed` | `REQUIRED` | `numpy` | `atom` | charge_spin, cooperative_cancel, 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
+`2`.  Query it without importing an algorithm
 implementation or resolving a model:
 
 ```python

mdescriptor-0.2.6/docs/gui-adaptation-baseline.md

@@ -0,0 +1,80 @@
+# GUI adaptation baseline
+
+This document is the versioned contract for a GUI that discovers and runs
+MDescriptor descriptors. It describes the public seams; private kernel
+classes, native symbols, and model internals are not GUI interfaces.
+
+The package exposes this document through `mdescriptor.gui_baseline()` and
+reports `baseline_version: "1"` from `mdescriptor.get_runtime_info()`.
+
+## Discovery and versions
+
+`list_descriptors()` returns the registered descriptor names. For each name,
+`describe_descriptor(name)` returns a JSON-safe object with these fields:
+
+`schema_version`, `name`, `descriptor_version`, `display_name`, `description`,
+`category`, `level`, `backend`, `execution_engine`, `capabilities`,
+`parameters`, `execution`, `input`, `output`, and `asset`.
+
+`schema_version` is the metadata-envelope version and is currently `2`.
+`descriptor_version` identifies the individual descriptor contract and is
+currently the string `"1"` for the built-ins. A GUI should check both before
+persisting or reconstructing metadata-driven configurations.
+
+`list_descriptors(detailed=True)` returns one JSON-safe summary record per
+descriptor with `name`, `descriptor_version`, `display_name`, `category`, and
+`level`. The default call remains the immutable tuple of names.
+
+`backend` identifies the adapter/backend compatibility label. It is not a
+promise about the currently selected native implementation. `execution_engine`
+identifies the default numerical engine. For example, DPA4 and DPA4C expose
+`backend: "numpy"` for their model/runtime adapter and
+`execution_engine: "cpp"` when the native extension is available.
+
+## Parameters and execution
+
+Parameter schemas use JSON-safe values. Supported schema types are `integer`,
+`number`, `boolean`, `string`, `enum`, `species`, `model`, `array`, and
+`object`; object schemas may contain nested `properties`, and array schemas
+may contain `items`. The `parameters` object is the canonical constructor
+surface; implementation-only options must not be synthesized by the GUI.
+
+The current built-ins advertise CPU execution (`execution.devices == ["cpu"]`)
+and may advertise `num_threads` and `cooperative_cancel` independently.
+Cancellation is cooperative and is reported as the public `CancelledError`.
+CUDA/GPU execution is not available in this release. A GUI must not offer a
+CUDA device for built-in descriptors; selecting one produces a structured
+`unsupported_device` configuration error. Future GPU support requires a
+device-specific kernel and matching platform wheels.
+
+## Input policy
+
+`StructureBatch` is the canonical flattened input. GUI frame records can be
+passed to `StructureBatch.from_frames()` when they expose `numbers`,
+`positions`, `cell`, `pbc`, and `id`; the helper generates the flattened
+arrays and cumulative offsets. Each frame is either
+`isolated` (all PBC flags false) or `fully_periodic` (all flags true); partial
+periodicity is invalid. A descriptor that only supports fully periodic input
+rejects isolated frames at the public adapter boundary with
+`UnsupportedPeriodicityError` (a `DescriptorInputError` subclass), code
+`unsupported_periodicity`, and path `["input", "periodicity"]`.
+LodeSphericalExpansion is periodic-only.
+
+The GUI should use the declared `input.periodicity`, `input.mixed_periodicity`,
+spin fields, and the structured error payload instead of inferring support
+from implementation names or exception text. Descriptors declaring both
+`isolated` and `fully_periodic` accept those frame kinds in one batch;
+periodic-only descriptors reject a batch containing an isolated frame.
+
+On Windows, import `mdescriptor` during single-threaded startup, before the GUI
+starts any background stdin/stdio reader. The package preloads the native
+binary at that point; an embedding host may also call
+`mdescriptor.preload_native()` explicitly during startup.
+
+## Results and lifecycle
+
+Configurations and results carry their own schema versions. Descriptors are
+closed explicitly after use; metadata snapshots remain available after close.
+Unknown descriptor names, unsupported options, unavailable assets, and
+unsupported input should be shown as structured errors rather than treated as
+native implementation failures.

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/scripts/verify_wheel.py

@@ -178,6 +178,12 @@ def main(argv: list[str] | None = None) -> int:
         target = package_file.parent.parent
     if not package_file.is_relative_to(target):
         raise SystemExit(f"wheel verification imported {package_file}, not {target}")
+    baseline = mdescriptor.gui_baseline()
+    if not baseline.startswith("# GUI adaptation baseline"):
+        raise SystemExit("GUI adaptation baseline resource is missing or invalid")
+    runtime = mdescriptor.get_runtime_info()
+    if runtime.get("baseline_version") != mdescriptor.GUI_BASELINE_VERSION:
+        raise SystemExit("GUI adaptation baseline version is missing or inconsistent")
     _verify_vendored_openblas(mdescriptor)
     names = mdescriptor.list_descriptors()
     if len(names) != 28 or len(set(names)) != 28:

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/src/mdescriptor/__init__.py

@@ -1,8 +1,11 @@
 """Stable MDescriptor contracts and explicit registry functions."""
 
+from importlib import resources
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as package_version
+from pathlib import Path
 
+from ._runtime import preload_native, preload_native_binary
 from .core import (
     CONFIGURATION_SCHEMA_VERSION,
     RESULT_SCHEMA_VERSION,
@@ -20,8 +23,12 @@ from .core import (
     OutputOptions,
     StructureBatch,
     StructureInput,
+    UnsupportedPeriodicityError,
 )
-from .registry import (
+
+preload_native_binary()
+
+from .registry import (  # noqa: E402  # preload native binary before registry metadata
     DESCRIPTOR_INFO_SCHEMA_VERSION,
     AssetPolicy,
     DescriptorConfiguration,
@@ -35,6 +42,28 @@ from .registry import (
 )
 
 API_VERSION = 1
+GUI_BASELINE_VERSION = "1"
+
+
+def gui_baseline() -> str:
+    """Return the packaged GUI adaptation contract document."""
+
+    resource = resources.files("mdescriptor").joinpath(
+        "docs", "gui-adaptation-baseline.md"
+    )
+    try:
+        return resource.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        # Source checkouts are usable before the CMake install step.  Wheels
+        # always take the resource branch because CMake installs the document
+        # under the package directory.
+        source_document = (
+            Path(__file__).resolve().parents[2] / "docs" / "gui-adaptation-baseline.md"
+        )
+        try:
+            return source_document.read_text(encoding="utf-8")
+        except FileNotFoundError as exc:
+            raise RuntimeError("GUI adaptation baseline is not installed") from exc
 
 try:
     from ._version import __version__
@@ -51,6 +80,7 @@ def get_runtime_info() -> dict[str, str | int]:
     return {
         "version": __version__,
         "api_version": API_VERSION,
+        "baseline_version": GUI_BASELINE_VERSION,
         "configuration_schema_version": CONFIGURATION_SCHEMA_VERSION,
         "descriptor_info_schema_version": DESCRIPTOR_INFO_SCHEMA_VERSION,
         "result_schema_version": RESULT_SCHEMA_VERSION,
@@ -58,6 +88,7 @@ def get_runtime_info() -> dict[str, str | int]:
 
 __all__ = [
     "API_VERSION",
+    "GUI_BASELINE_VERSION",
     "AssetPolicy",
     "CancelledError",
     "ClosedDescriptorError",
@@ -79,11 +110,14 @@ __all__ = [
     "RESULT_SCHEMA_VERSION",
     "StructureBatch",
     "StructureInput",
+    "UnsupportedPeriodicityError",
     "builtin_registry",
     "create_descriptor",
     "describe_descriptor",
     "get_descriptor",
     "get_runtime_info",
+    "gui_baseline",
     "list_descriptors",
+    "preload_native",
     "__version__",
 ]

mdescriptor-0.2.6/src/mdescriptor/_runtime.py

@@ -0,0 +1,76 @@
+"""Small platform runtime setup kept independent of descriptor imports."""
+
+from __future__ import annotations
+
+import ctypes
+import importlib
+import importlib.machinery
+import importlib.util
+import os
+from pathlib import Path
+from typing import Any
+
+_DLL_DIRECTORIES: list[Any] = []
+_NATIVE_HANDLES: list[Any] = []
+_NATIVE_PRELOAD_ATTEMPTED = False
+
+
+def native_extension_available() -> bool:
+    """Return whether the private native module resolves to an extension binary."""
+
+    # On Windows, an extension file can exist while one of its DLL
+    # dependencies is unavailable.  ``preload_native_binary`` performs the
+    # loadability check before the registry is assembled, so do not fall back
+    # to the filename-only probe after that check has run.
+    if os.name == "nt" and _NATIVE_PRELOAD_ATTEMPTED:
+        return bool(_NATIVE_HANDLES)
+
+    try:
+        spec = importlib.util.find_spec("mdescriptor._native")
+    except (ImportError, ValueError):
+        return False
+    if spec is None or spec.origin is None:
+        return False
+    origin = str(spec.origin)
+    return any(origin.endswith(suffix) for suffix in importlib.machinery.EXTENSION_SUFFIXES)
+
+
+def preload_native_binary() -> None:
+    """Load the packaged native binary before an embedded host starts threads.
+
+    Windows OpenBLAS builds can initialize a worker pool from DLL load code.
+    Loading the extension binary during normal package startup moves that work
+    before a GUI/stdio host starts its background pipe readers. The Python
+    extension module is not initialized here, so static registry metadata stays
+    independent of ``mdescriptor._native`` in ``sys.modules``.
+    """
+
+    global _NATIVE_PRELOAD_ATTEMPTED
+
+    if os.name != "nt":
+        return
+    _NATIVE_PRELOAD_ATTEMPTED = True
+    loader = getattr(ctypes, "WinDLL", None)
+    if loader is None:
+        return
+    package_directory = Path(__file__).resolve().parent
+    add_dll_directory = getattr(os, "add_dll_directory", None)
+    if add_dll_directory is not None:
+        _DLL_DIRECTORIES.append(add_dll_directory(str(package_directory)))
+    for path in sorted(package_directory.glob("_native*.pyd")):
+        try:
+            _NATIVE_HANDLES.append(loader(str(path)))
+        except OSError:
+            # Leave the normal import path to report a useful missing-runtime
+            # error. Source checkouts without a built extension also land here.
+            continue
+        break
+
+
+def preload_native() -> None:
+    """Initialize the Python native module from a single-threaded startup hook."""
+
+    importlib.import_module("mdescriptor._native")
+
+
+__all__ = ["preload_native"]

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/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.4'
-__version_tuple__ = version_tuple = (0, 2, 4)
+__version__ = version = '0.2.6'
+__version_tuple__ = version_tuple = (0, 2, 6)
 
-__commit_id__ = commit_id = 'gca05e625e'
+__commit_id__ = commit_id = 'g1887016ed'

{mdescriptor-0.2.4 → mdescriptor-0.2.6}/src/mdescriptor/core/__init__.py

@@ -9,6 +9,7 @@ from .errors import (
     DescriptorInputError,
     MDescriptorError,
     ModelLoadError,
+    UnsupportedPeriodicityError,
 )
 from .input import StructureBatch, StructureInput, batch_from_ase, coerce_batch
 from .options import (
@@ -45,6 +46,7 @@ __all__ = [
     "OutputOptions",
     "StructureBatch",
     "StructureInput",
+    "UnsupportedPeriodicityError",
     "batch_from_ase",
     "coerce_batch",
     "normalize_species",