Source code for nvalchemi.csp.volume

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Crystallography Open Database (COD)-derived atomic volume data and
formula-unit volume estimates.
"""

from __future__ import annotations

import math
from collections.abc import Mapping
from numbers import Integral, Real
from typing import TYPE_CHECKING

import torch

from nvalchemi.csp._data_tables import ATOMIC_VOLUMES

if TYPE_CHECKING:
    from torch import Tensor


[docs] def get_default_atomic_volumes() -> dict[int, float]: """Return a fresh copy of the bundled COD-derived atomic volume table. Returns ------- atomic_volumes : dict[int, float] Per-atom volume contributions in cubic angstroms, keyed by atomic number. The returned mapping is independent of library state and may be modified. """ return ATOMIC_VOLUMES.copy()
def _validated_atomic_volumes(atomic_volumes: Mapping[int, float]) -> dict[int, float]: """Copy a table of finite positive per-atom volumes keyed by atomic number.""" if not isinstance(atomic_volumes, Mapping): raise TypeError("atomic_volumes must be a mapping") validated: dict[int, float] = {} for key, value in atomic_volumes.items(): if isinstance(key, bool) or not isinstance(key, Integral): raise TypeError("atomic_volumes keys must be integral atomic numbers") number = int(key) if not 1 <= number <= 118: raise ValueError( "atomic_volumes keys must be valid atomic numbers in [1, 118]" ) if isinstance(value, bool) or not isinstance(value, Real): raise TypeError("atomic_volumes values must be real numbers") try: volume = float(value) except OverflowError as error: raise ValueError( "atomic_volumes values must be finite and positive" ) from error if not math.isfinite(volume) or volume <= 0: raise ValueError("atomic_volumes values must be finite and positive") validated[number] = volume return validated
[docs] def estimate_formula_unit_volume( atomic_numbers: Tensor, *, atomic_volumes: Mapping[int, float] | None = None, ) -> float: """Estimate formula-unit volume by summing per-atom contributions. Parameters ---------- atomic_numbers : torch.Tensor, shape ``[A]`` Nonempty one-dimensional tensor using ``torch.uint8``, ``torch.int8``, ``torch.int16``, ``torch.int32``, or ``torch.int64``. atomic_volumes : Mapping[int, float], optional Complete replacement table in cubic angstroms per atom. When omitted, the bundled COD-derived table is used. A custom mapping does not overlay defaults. Returns ------- volume : float Estimated formula-unit volume in cubic angstroms. Raises ------ TypeError If ``atomic_numbers`` is not a tensor, has an unsupported dtype, or ``atomic_volumes`` is not a mapping. ValueError If the tensor is empty or malformed, a table value is invalid, or one or more atomic numbers are missing from the selected table. Examples -------- >>> import torch >>> estimate_formula_unit_volume(torch.tensor([6, 8])) 23.78 """ if not isinstance(atomic_numbers, torch.Tensor): raise TypeError("atomic_numbers must be a torch.Tensor") if atomic_numbers.ndim != 1 or atomic_numbers.numel() == 0: raise ValueError("atomic_numbers must be a nonempty one-dimensional tensor") integral_dtypes = { torch.uint8, torch.int8, torch.int16, torch.int32, torch.int64, } if atomic_numbers.dtype not in integral_dtypes: raise TypeError( "atomic_numbers must use torch.uint8, torch.int8, torch.int16, " "torch.int32, or torch.int64" ) values = atomic_numbers.detach().to(device="cpu", dtype=torch.int64).tolist() if any(not 1 <= number <= 118 for number in values): raise ValueError("atomic_numbers must contain valid atomic numbers in [1, 118]") table = ( get_default_atomic_volumes() if atomic_volumes is None else _validated_atomic_volumes(atomic_volumes) ) missing = sorted(set(values).difference(table)) if missing: raise ValueError( f"No atomic volume is available for atomic number(s): {missing}" ) total = math.fsum(table[number] for number in values) if not math.isfinite(total): raise ValueError("formula-unit volume estimate must be finite") return total