GraphAtoms 2.3.1__tar.gz → 2.3.3__tar.gz

{graphatoms-2.3.1 → graphatoms-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: graphatoms
-Version: 2.3.1
+Version: 2.3.3
 Summary: The Chemical Core Class for Graph Theory Analysis.
 Keywords: chemistry,graph theory,reaction,event,KMC
 Author: LiuGaoyong
@@ -14,12 +14,12 @@ Requires-Dist: ase
 Requires-Dist: pymatgen>2023.6
 Requires-Dist: rdkit>=2025
 Requires-Dist: numpy>=2,<3
-Requires-Dist: pandas>=2,<4
 Requires-Dist: scipy>=1.10,<2
 Requires-Dist: scikit-learn>=1.5
 Requires-Dist: array-api-compat>=1.10
 Requires-Dist: array-api-extra>=0.10
 Requires-Dist: pyarrow
+Requires-Dist: pandas
 Requires-Dist: igraph>=0.11
 Requires-Dist: h5py>=3.16
 Requires-Dist: numpydantic

{graphatoms-2.3.1 → graphatoms-2.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "graphatoms"
-version = "2.3.1"
+version = "2.3.3"
 readme = "README.md"
 description = "The Chemical Core Class for Graph Theory Analysis."
 license-files = ["src/LICENSE"]
@@ -27,12 +27,12 @@ dependencies = [
     "pymatgen>2023.6",
     "rdkit>=2025",
     "numpy>=2,<3",
-    "pandas>=2,<4",
     "scipy>=1.10,<2",
     "scikit-learn>=1.5",
     "array-api-compat>=1.10",
     "array_api-extra>=0.10",
     "pyarrow",
+    "pandas",
     "igraph>=0.11",
     "h5py>=3.16",
     "numpydantic",
@@ -146,29 +146,29 @@ benchmark = "pytest -s src/tests-benchmark/*.py"
 
 [tool.pixi.dependencies]
 python = ">=3.12"
-pytest = ">=9.0.3,<10"
-array-api-compat = ">=1.15.0,<2"
-array-api-extra = ">=0.11.0,<0.12"
-array-api-strict = ">=2.5,<3"
-ase = ">=3.28.0,<4"
-pymatgen = ">=2026.5.4,<2027"
-rdkit = ">=2025.9.5,<2027"
-openbabel = ">=3.1.1,<4"
-pyarrow = ">=21.0.0,<25"
-scikit-learn = ">=1.8.0,<2"
-python-igraph = ">=0.11.9,<0.12"
-numpy = ">=2.0.0,<3"
-pydantic = ">=2.10.0,<3"
-numpydantic = ">=1.8.1,<2"
-python-snappy = ">=0.7.3,<0.8"
-h5py = ">=3.16.0,<4"
-hydra-core = ">=1.3.2,<2"
-tomli-w = ">=1.2.0,<2"
-loguru = ">=0.7.3,<0.8"
-jupyterlab = ">=4.5.8,<5"
-joblib = ">=1.1.0,<2"
-ovld = ">=0.5.15,<0.6"
-pytest-xdist = ">=3.8.0,<4"
-executorlib = ">=1.8,<2"
-typer = ">=0.20,<1"
-grpcio = ">=1.52.0,<2"
+pytest = ">=8"
+array-api-compat = ">=1.15.0"
+array-api-extra = ">=0.11.0"
+array-api-strict = ">=2.5"
+ase = ">=3.28.0"
+pymatgen = ">=2026.5.4"
+rdkit = ">=2025.9.5"
+openbabel = ">=3.1.1"
+pyarrow = ">=21.0.0"
+scikit-learn = ">=1.8.0"
+python-igraph = ">=0.11.9"
+numpy = ">=2.0.0"
+pydantic = ">=2.10.0"
+numpydantic = ">=1.8.1"
+python-snappy = ">=0.7.3"
+h5py = ">=3.16"
+hydra-core = ">=1.3.0"
+tomli-w = ">=1.2.0"
+loguru = ">=0.7.3"
+jupyterlab = ">=4.5.8"
+joblib = ">=1.1.0"
+ovld = ">=0.5.15"
+pytest-xdist = ">=3.8.0"
+executorlib = ">=1.8"
+typer = ">=0.20"
+grpcio = ">=1.52.0"

{graphatoms-2.3.1 → graphatoms-2.3.3}/pyproject.toml.orig

@@ -12,7 +12,7 @@ graphatoms-network = "graphatoms.enterpoint.network:main"
 graphatoms-run = "graphatoms.enterpoint.runner:run"
 [project]
 name = "graphatoms"
-version = "2.3.1"
+version = "2.3.3"
 readme = "README.md"
 description = "The Chemical Core Class for Graph Theory Analysis."
 authors = [{ name = "LiuGaoyong", email = "liugaoyong_88@163.com" }]
@@ -39,12 +39,12 @@ dependencies = [
 
     # Scientific Computing
     "numpy>=2,<3",
-    "pandas>=2,<4",
     "scipy>=1.10,<2",
     "scikit-learn>=1.5",
     "array-api-compat>=1.10",
     "array_api-extra>=0.10",
     "pyarrow",
+    "pandas",
 
     # Graph Theory
     "igraph>=0.11", # high performance graph library based on C
@@ -145,29 +145,29 @@ benchmark = "pytest -s src/tests-benchmark/*.py"
 
 [tool.pixi.dependencies]
 python = ">=3.12"
-pytest = ">=9.0.3,<10"
-array-api-compat = ">=1.15.0,<2"
-array-api-extra = ">=0.11.0,<0.12"
-array-api-strict = ">=2.5,<3"
-ase = ">=3.28.0,<4"
-pymatgen = ">=2026.5.4,<2027"
-rdkit = ">=2025.9.5,<2027"
-openbabel = ">=3.1.1,<4"
-pyarrow = ">=21.0.0,<25"
-scikit-learn = ">=1.8.0,<2"
-python-igraph = ">=0.11.9,<0.12"
-numpy = ">=2.0.0,<3"
-pydantic = ">=2.10.0,<3"
-numpydantic = ">=1.8.1,<2"
-python-snappy = ">=0.7.3,<0.8"
-h5py = ">=3.16.0,<4"
-hydra-core = ">=1.3.2,<2"
-tomli-w = ">=1.2.0,<2"
-loguru = ">=0.7.3,<0.8"
-jupyterlab = ">=4.5.8,<5"
-joblib = ">=1.1.0,<2"
-ovld = ">=0.5.15,<0.6"
-pytest-xdist = ">=3.8.0,<4"
-executorlib = ">=1.8,<2"
-typer = ">=0.20,<1"
-grpcio = ">=1.52.0,<2"
+pytest = ">=8"
+array-api-compat = ">=1.15.0"
+array-api-extra = ">=0.11.0"
+array-api-strict = ">=2.5"
+ase = ">=3.28.0"
+pymatgen = ">=2026.5.4"
+rdkit = ">=2025.9.5"
+openbabel = ">=3.1.1"
+pyarrow = ">=21.0.0"
+scikit-learn = ">=1.8.0"
+python-igraph = ">=0.11.9"
+numpy = ">=2.0.0"
+pydantic = ">=2.10.0"
+numpydantic = ">=1.8.1"
+python-snappy = ">=0.7.3"
+h5py = ">=3.16"
+hydra-core = ">=1.3.0"
+tomli-w = ">=1.2.0"
+loguru = ">=0.7.3"
+jupyterlab = ">=4.5.8"
+joblib = ">=1.1.0"
+ovld = ">=0.5.15"
+pytest-xdist = ">=3.8.0"
+executorlib = ">=1.8"
+typer = ">=0.20"
+grpcio = ">=1.52.0"

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/dataclasses/_pydanticMixin.py

@@ -229,7 +229,11 @@ class __Json(PydanticConvertFactoryMixin):
                 indent=indent,
             )
         )
-        filename.write_text(self.to_str(**kwargs), "utf-8")
+        bytesutils.atomic_write_text(
+            target=filename,
+            text=self.to_str(**kwargs),
+            encoding="utf-8",
+        )
         return filename
 
     @classmethod
@@ -260,13 +264,15 @@ class __Toml(PydanticConvertFactoryMixin):
                 numpy_ndarray_compatible=True,
             )
         )
-        with filename.open("wb") as f:
-            toml_w.dump(
+        bytesutils.atomic_write_text(
+            target=filename,
+            text=toml_w.dumps(
                 self.to_dict(**kwargs),
-                f,
                 indent=indent,
                 multiline_strings=True,
-            )
+            ),
+            encoding="utf-8",
+        )
         return filename
 
     @classmethod
@@ -301,16 +307,17 @@ class __Yaml(PydanticConvertFactoryMixin):
                 numpy_ndarray_compatible=True,
             )
         )
-        with filename.open("w", encoding="utf-8") as f:
-            f.write(
-                OmegaConf.to_yaml(
-                    self.to_dict(**kwargs),
-                    # f,
-                    # encoding="utf-8",
-                    # # default_flow_style=False,
-                    # indent=4,
-                )
-            )
+        bytesutils.atomic_write_text(
+            target=filename,
+            text=OmegaConf.to_yaml(
+                self.to_dict(**kwargs),
+                # f,
+                # encoding="utf-8",
+                # # default_flow_style=False,
+                # indent=4,
+            ),
+            encoding="utf-8",
+        )
         return filename
 
     @classmethod
@@ -345,10 +352,14 @@ class __Npz(PydanticConvertFactoryMixin):
                 numpy_ndarray_compatible=True,
             )
         )
-        (np.savez_compressed if compress else np.savez)(
-            filename,
-            allow_pickle=False,
-            **self.to_dict(**kwargs),
+        func = np.savez_compressed if compress else np.savez
+        bytesutils.atomic_write(
+            target=filename,
+            writer=lambda p: func(
+                p,
+                allow_pickle=False,
+                **self.to_dict(**kwargs),
+            ),
         )
         return filename
 
@@ -411,7 +422,14 @@ class __Pickle(PydanticConvertFactoryMixin):
                 numpy_ndarray_compatible=True,
             )
         )
-        dump(self.to_dict(**kwargs), filename, compress=compress)
+        bytesutils.atomic_write(
+            target=filename,
+            writer=lambda p: dump(
+                value=self.to_dict(**kwargs),
+                filename=p,
+                compress=compress,  # type: ignore
+            ),
+        )
         return filename
 
     @classmethod

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/dataclasses/_pydanticModel.py

@@ -126,7 +126,7 @@ class OurBaseModel(PydanticFactoryMixin, _IndexMaskMixin):
                 if v0.shape != v1.shape:
                     return False
                 if np.all(v0 == v1):
-                    return True
+                    continue
                 elif not np.allclose(v0, v1):
                     return False
             else:

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/enterpoint/network/_clsnetwork.py

@@ -27,6 +27,7 @@ from graphatoms.reaction import (
 )
 from graphatoms.system import Cluster, Gas, SysGraph, System
 from graphatoms.system.database import DatabaseABC, get_db
+from graphatoms.utils.bytestool import atomic_write, atomic_write_text
 
 __all__ = [
     "MetaData",
@@ -88,8 +89,9 @@ class ReactionNetwork(Mapping[str, tuple[EventInfo, EventBase]]):
                 + " Please delete it or use `restart=True`."
             )
             self.__path.mkdir(parents=True, exist_ok=True)
-            self.__path_exploration_recorder.write_text(
-                RecorderInfo.get_csv_title() + "\n"
+            atomic_write_text(
+                self.__path_exploration_recorder,
+                RecorderInfo.get_csv_title() + "\n",
             )
             self.__recorder = Recorder()
             self.__scheduler = Scheduler()
@@ -130,6 +132,7 @@ class ReactionNetwork(Mapping[str, tuple[EventInfo, EventBase]]):
         config: Config,
         *args,
         restart: bool | None = None,
+        remote_retry_times: float = 2.0,
         remote_mode: bool = False,
         **kwargs,
     ) -> Self:  # type: ignore
@@ -152,7 +155,7 @@ class ReactionNetwork(Mapping[str, tuple[EventInfo, EventBase]]):
                     )
                     break
                 except Exception as e:
-                    time.sleep(0.5)
+                    time.sleep(abs(remote_retry_times))
                     err = e
             if err is not None:
                 raise RuntimeError(
@@ -535,8 +538,11 @@ class ReactionNetwork(Mapping[str, tuple[EventInfo, EventBase]]):
                     msg = f"Event {event._string()} failed "
                     msg += f"to simplify. because of {e}"
                     fname = self.__path / "event-simplify-fail.pkl"
-                    fname.with_suffix(".err").write_text(msg)
-                    fname.write_bytes(pickle.dumps(event))
+                    atomic_write_text(fname.with_suffix(".err"), msg)
+                    atomic_write(
+                        fname,
+                        writer=lambda p: p.write_bytes(pickle.dumps(event)),
+                    )
                     event.R.write_npz(fname.with_suffix(".R.npz"))
                     event.P.write_npz(fname.with_suffix(".P.npz"))
                     if event.G is not None:
@@ -789,8 +795,10 @@ if __name__ == "__main__":
         if "merge" not in zzzz_path.name:
             p = zzzz_path / "event"
             (p / "recorder.json").unlink(missing_ok=True)
-            with open(p / "recorder.json", "w") as f:
-                json.dump({}, f, indent=4)
+            atomic_write_text(
+                p / "recorder.json",
+                json.dumps({}, indent=4),
+            )
             network_lst.append(
                 ReactionNetwork(
                     zzzz_path / "event",

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/enterpoint/network/_metadata.py

@@ -1,6 +1,7 @@
 import dataclasses as dc
+import types
 from pathlib import Path
-from typing import Any, Self, override
+from typing import Any, Self, Union, get_args, get_origin, override
 
 import numpy as np
 import pandas as pd
@@ -10,10 +11,30 @@ from graphatoms.dataclasses import OurBaseModel
 from graphatoms.enterpoint.config import Config, EventConfig
 from graphatoms.reaction import EventBase, EventInfo
 from graphatoms.system.bonds import matchmode2nmatch
+from graphatoms.utils.bytestool import atomic_write
 
 __all__ = ["MetaData"]
 
 
+def _is_list_of_optional_str(annotation: Any) -> bool:
+    """Whether the annotation is ``list[str | None]``."""
+    if get_origin(annotation) is not list:
+        return False
+    element = get_args(annotation)[0]
+    if get_origin(element) not in (Union, types.UnionType):
+        return False
+    return set(get_args(element)) == {str, type(None)}
+
+
+def _missing_to_none(value: Any) -> Any:
+    """Convert a missing value marker of pandas to ``None``."""
+    if value is None or value is pd.NA:
+        return None
+    if isinstance(value, float) and np.isnan(value):
+        return None
+    return value
+
+
 class _MetaDataBasic(OurBaseModel, EventConfig):
     gas_sticking: dict[str, NonNegativeFloat] = {}
 
@@ -108,7 +129,23 @@ class _MetaDataTable(BaseModel):
 
     @classmethod
     def from_dataframe(cls, df: pd.DataFrame) -> Self:
-        return cls(**{k: df[k].to_list() for k in df.columns})
+        """Create the table from a DataFrame.
+
+        Note:
+            Since pandas 3.0, a string column containing missing values is
+            read back as the new default string dtype (``str``), whose
+            missing value marker is ``numpy.nan`` instead of ``None``.
+            Such ``nan`` values are rejected by the ``str | None`` fields,
+            so they are converted back to ``None`` here.
+        """
+        data: dict[str, list[Any]] = {}
+        for k in df.columns:
+            values: list[Any] = df[k].to_list()
+            field = cls.__pydantic_fields__.get(k)
+            if field is not None and _is_list_of_optional_str(field.annotation):
+                values = [_missing_to_none(v) for v in values]
+            data[k] = values
+        return cls(**data)
 
     def merge(self, other: Self, idxs: list[int] | None = None) -> None:
         if idxs is None:
@@ -187,7 +224,10 @@ class MetaData(BaseModel):
 
     def persistence(self, path: Path | str) -> None:
         self.basic.write_json(Path(path) / "metadata-basic.json")
-        self.table.dataframe.to_feather(Path(path) / "metadata-table.feather")
+        atomic_write(
+            Path(path) / "metadata-table.feather",
+            writer=lambda p: self.table.dataframe.to_feather(p),
+        )
 
     @classmethod
     def from_storage(cls, path: Path | str) -> Self:

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/enterpoint/network/_scheduler.py

@@ -9,6 +9,7 @@ from sklearn.metrics.pairwise import cosine_similarity
 
 from graphatoms.dataclasses._numpydantic import NDArray
 from graphatoms.system import SysGraph  # type: ignore
+from graphatoms.utils.bytestool import atomic_write
 
 
 class Scheduler(BaseModel):
@@ -35,17 +36,21 @@ class Scheduler(BaseModel):
         save: Callable = np.savez_compressed if compress else np.savez
         dct = {f"{k}_is_fixed": v for k, v in self.is_fixed.items()}
         dct = {f"{k}_dR": v for k, v in self.dR.items()} | dct
-        save(filename, allow_pickle=False, **dct)
+        atomic_write(
+            target=filename,
+            writer=lambda p: save(p, allow_pickle=False, **dct),
+        )
         return filename
 
     @classmethod
     @validate_call
     def read_npz(cls, filename: FilePath, *args, **kwargs) -> Self:
         data: dict[str, dict[str, NDArray]] = defaultdict(dict)
-        dct: Mapping[str, NDArray] = np.load(filename)
-        for k, v in dct.items():
-            k2, k1 = k.split("_")
-            data[k1][k2] = v
+        with np.load(filename) as npz:
+            dct: Mapping[str, NDArray] = npz
+            for k, v in dct.items():
+                k2, k1 = k.rsplit("_", 1)
+                data[k1][k2] = v
         return cls(**data)
 
     def can_be_skip(
@@ -58,7 +63,6 @@ class Scheduler(BaseModel):
         **kwargs,
     ) -> tuple[bool, float]:
         diffpositions = np.asarray(diffpositions, dtype=float)
-        print(diffpositions)
         assert 0 <= thetacutoff <= 180, "thetacutoff must be in 0-180"
         if isinstance(graph, str):
             if is_fixed is None:
@@ -106,7 +110,6 @@ class Scheduler(BaseModel):
             cos: np.ndarray = cosine_similarity(dR, dR_new)
             if np.max(cos) <= np.cos(np.deg2rad(thetacutoff)):
                 self.dR[key] = np.vstack((dR, dR_new))  # row_stack
-                print(self.dR[key])
                 return False, np.max(cos)
             return True, np.max(cos)
 
@@ -151,5 +154,8 @@ if __name__ == "__main__":
     plt.title("Blue: Keep; Red: Skip")
 
     p = Path(__file__).with_suffix(".png")
-    plt.savefig(p)
+    atomic_write(
+        p,
+        writer=lambda p: plt.savefig(p),
+    )
     obj.write_npz(p.with_suffix(".npz"))

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/enterpoint/parallel/__init__.py

@@ -10,7 +10,7 @@ from graphatoms.enterpoint.parallel._base import (
 )
 from graphatoms.enterpoint.parallel._dask import DaskExecutor
 from graphatoms.enterpoint.parallel._executorlib import ExecutorLibExecutor
-from graphatoms.enterpoint.parallel._ray import _RAY_AVAILABLE, RayExecutor, ray
+from graphatoms.enterpoint.parallel._ray import RayExecutor, ray
 
 __all__ = [
     "SerialExecutor",
@@ -18,6 +18,14 @@ __all__ = [
     "ParallelExecutorABC",
     "get_executor",
 ]
+BACKENDS = [
+    "serial",
+    "multiprocessing",
+    "ray",
+    "dask",
+    "executorlib",
+    "joblib",
+]
 
 
 def get_executor(
@@ -40,7 +48,11 @@ def get_executor(
     backend = str(backend).lower()
     if backend in ("ray",):
         return RayExecutor(nworkers=nworkers, **kwargs)  # type: ignore[arg-type]
-    elif backend in ("dask",):
+    # `ncpus_for_tasks` only applies to the ray backend; `RunnerABC` passes
+    # it unconditionally, so drop it for the other backends instead of
+    # forwarding it to `ProcessPoolExecutor`.
+    kwargs.pop("ncpus_for_tasks", None)
+    if backend in ("dask",):
         return DaskExecutor(nworkers=nworkers, **kwargs)  # type: ignore[arg-type]
     elif backend in ("executorlib",):
         return ExecutorLibExecutor(  # type: ignore[arg-type]
@@ -53,10 +65,7 @@ def get_executor(
             nworkers = None
         return MultiprocessingExecutor(nworkers=nworkers, **kwargs)  # type: ignore[call-arg]
     else:
-        raise ValueError(
-            f"Unknown backend: {backend} Available: "
-            f"{['serial', 'multiprocessing', 'ray', 'dask', 'executorlib']}"
-        )
+        raise ValueError(f"Unknown backend: {backend} Available: {BACKENDS}")
 
 
 def executor_map(
@@ -69,12 +78,19 @@ def executor_map(
 ) -> Sequence[Any]:
     if isinstance(executor, RayExecutor):
         dct: dict[int, ray.ObjectRef] = {}
+        # Hold a strong reference to every deduplicated object.  Keying the
+        # cache on `id(v)` alone is only safe while the objects stay alive;
+        # if an intermediate object were collected, CPython could hand its
+        # `id` to a *different* object and the wrong value would be
+        # substituted into a task.
+        keepalive: list[Any] = []
         remote_params: list[dict[str, ray.ObjectRef]] = []
         for params in fn_params:
             item: dict[str, ray.ObjectRef] = {}
             for k, v in params.items():
                 if id(v) not in dct:
                     dct[id(v)] = ray.put(v)
+                    keepalive.append(v)
                 item[k] = dct[id(v)]
             remote_params.append(item)
         fn_params = remote_params

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/enterpoint/parallel/_base.py

@@ -111,12 +111,21 @@ class MultiprocessingExecutor(ParallelExecutorABC):
             return_when=cf.FIRST_COMPLETED,
             timeout=timeout,
         )
-        self.__executor.map
-        return self.get(list(done)[0]), undone  # type: ignore[override]
+        if len(done) == 0:
+            raise TimeoutError(
+                "concurrent.futures.wait() returned no finished task "
+                f"within timeout={timeout!r}."
+            )
+        # `FIRST_COMPLETED` may return *several* futures at once.  Only one
+        # result can be returned by this API, so the other already-finished
+        # futures must be pushed back into the remaining list; otherwise their
+        # results are silently dropped by callers that loop until the list is
+        # empty.
+        done = list(done)
+        return self.get(done[0]), list(undone) + done[1:]  # type: ignore[override]
 
     @override
     def map(self, fn, *iterables, timeout=None, chunksize=1) -> list[Any]:
-        print(iterables)
         return list(
             self.__executor.map(
                 fn,
@@ -128,6 +137,16 @@ class MultiprocessingExecutor(ParallelExecutorABC):
 
 
 class SerialExecutor(MultiprocessingExecutor):
+    """Run tasks one at a time.
+
+    .. warning::
+        This is *not* an in-process executor: it delegates to a
+        single-worker :class:`~concurrent.futures.ProcessPoolExecutor`, so
+        every task and its arguments must be picklable and each call runs in a
+        forked child process.  See the project bug report for the implications
+        under Slurm.
+    """
+
     @override
-    def __init__(self, *, nworkers=None, **kwargs) -> None:
-        super().__init__(nworkers=1, **kwargs)
+    def __init__(self, *a, **kw) -> None:
+        super().__init__(nworkers=1)

{graphatoms-2.3.1 → graphatoms-2.3.3}/src/graphatoms/enterpoint/parallel/_ray.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import weakref
 from collections.abc import Callable
@@ -18,6 +20,17 @@ if TYPE_CHECKING:
     import ray  # type: ignore
 
 
+###############################################################################
+# NOTE: `from __future__ import annotations` above is required, *not* optional.
+# `ray` is an optional dependency (it is only a dev dependency in
+# pyproject.toml), so when it is absent this module sets `ray = None`.  Without
+# postponed evaluation the `-> ray.ObjectRef` annotations below would be
+# evaluated eagerly at class-definition time and raise
+# `AttributeError: 'NoneType' object has no attribute 'ObjectRef'`, which makes
+# `import graphatoms.enterpoint.parallel` (and therefore `graphatoms-run`)
+# fail on any installation that does not happen to have ray installed.
+
+
 class RayExecutor(ParallelExecutorABC):
     """An executor backed by :mod:`ray`."""
 
@@ -35,15 +48,12 @@ class RayExecutor(ParallelExecutorABC):
             raise ImportError(
                 "ray is not installed. Install it with: pip install ray"
             )
-        try:
-            if not ray.is_initialized():  # type: ignore
-                ray.init(  # type: ignore
-                    ignore_reinit_error=True,
-                    num_cpus=nworkers,
-                    **kwargs,
-                )
-        except Exception:
-            pass
+        if not ray.is_initialized():  # type: ignore
+            ray.init(  # type: ignore
+                ignore_reinit_error=True,
+                num_cpus=nworkers,
+                **kwargs,
+            )
 
     @override
     def submit(
@@ -68,7 +78,7 @@ class RayExecutor(ParallelExecutorABC):
             func_ref = weakref.ref(func)  # type: ignore
         except TypeError:
 
-            def func_ref():  # type: ignore
+            def func_ref() -> Callable[..., Any]:  # type: ignore
                 return func
 
         self._remote_fn_cache[key] = (func_ref, remote_fn)  # type: ignore
@@ -90,8 +100,21 @@ class RayExecutor(ParallelExecutorABC):
         timeout: float | None = None,
         **kwargs,
     ) -> tuple[Any, list[ray.ObjectRef]]:  # type: ignore
-        done, unfinished = ray.wait(futures, timeout=timeout)  # type: ignore
-        return ray.get(done)[0], unfinished  # type: ignore
+        done, unfinished = ray.wait(  # type: ignore
+            futures,
+            timeout=timeout,
+            num_returns=1,
+            **kwargs,
+        )
+        if len(done) == 0:
+            raise TimeoutError(
+                "ray.wait() returned no finished task "
+                f"within timeout={timeout!r}."
+            )
+        # `ray.wait` defaults to `num_returns=1`, but a caller may ask for
+        # more.  Keep every finished ref accounted for so that no completed
+        # result is silently dropped from the caller's work queue.
+        return ray.get(done[0]), list(unfinished) + list(done[1:])  # type: ignore
 
     @override
     def map(self, fn, *iterables, timeout=None, chunksize=1) -> list[Any]: