# 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.
"""Space-group operations, crystal-system metadata, and sampling helpers.
The source CSP project supplies the pinned standard-setting Hall-number
mapping. Operation tables were regenerated from the spglib 2.7.0 Hall database
using that mapping; the bundled sampling prior is CSD-derived. Operations use
International space-group numbers ``1..230`` and store each fractional
operation as a ``[3, 4]`` matrix ``[R | t]``.
"""
from __future__ import annotations
import math
from collections.abc import Mapping
from enum import Enum
from functools import lru_cache
from numbers import Integral, Real
from types import MappingProxyType
from typing import Any, Literal, TypeAlias
import numpy as np
import torch
from pydantic import (
BaseModel,
ConfigDict,
Field,
field_serializer,
field_validator,
model_validator,
)
from torch import Tensor
from nvalchemi.csp._data_tables import SPACE_GROUP_PROBABILITIES
from nvalchemi.csp._space_group_tables import SG_OPS_IDX, SG_OPS_PTR, SYMM_OPS
from nvalchemi.csp._validation import positive_integer
Device: TypeAlias = torch.device | str | None
# Each entry is (first space-group number, last space-group number,
# zero-based crystal-system code). The codes follow the CrystalSystem enum below.
_CRYSTAL_SYSTEM_RANGES = (
(1, 2, 0),
(3, 15, 1),
(16, 74, 2),
(75, 142, 3),
(143, 167, 4),
(168, 194, 5),
(195, 230, 6),
)
# International numbers for chirality-preserving (proper-rotation-only) groups
# queried by :func:`is_sohncke_space_group`.
# fmt: off
_SOHNCKE = frozenset(
{
1, 3, 4, 5, 16, 17, 18, 19, 20, 21, 22, 23,
24, 75, 76, 77, 78, 79, 80, 89, 90, 91, 92, 93,
94, 95, 96, 97, 98, 143, 144, 145, 146, 149, 150, 151,
152, 153, 154, 155, 168, 169, 170, 171, 172, 173, 177,
178, 179, 180, 181, 182, 195, 196, 197, 198, 199,
207, 208, 209, 210, 211, 212, 213, 214,
}
)
# fmt: on
[docs]
class CrystalSystem(str, Enum):
"""The seven crystallographic crystal systems."""
TRICLINIC = "triclinic"
MONOCLINIC = "monoclinic"
ORTHORHOMBIC = "orthorhombic"
TETRAGONAL = "tetragonal"
TRIGONAL = "trigonal"
HEXAGONAL = "hexagonal"
CUBIC = "cubic"
def _validate_space_group(space_group: int) -> int:
"""Return an International space-group number after range validation."""
if isinstance(space_group, bool) or not isinstance(space_group, Integral):
raise TypeError("space_group must be an integer")
number = int(space_group)
if not 1 <= number <= 230:
raise ValueError("space_group must be in [1, 230]")
return number
def _validate_positive_integer(value: int, name: str) -> int:
"""Return a positive integral value, rejecting booleans."""
try:
return positive_integer(value, name=name)
except TypeError:
raise TypeError(f"{name} must be an integer") from None
def _validate_table() -> None:
"""Check that bundled operation and pointer tables have consistent shapes."""
if SYMM_OPS.ndim != 2 or SYMM_OPS.shape[1] != 12:
raise RuntimeError("space-group operations must have shape [K, 12]")
if SG_OPS_IDX.ndim != 1 or SG_OPS_PTR.shape != (231,):
raise RuntimeError("space-group pointer and index tables have invalid shapes")
if int(SG_OPS_PTR[0]) != 0 or int(SG_OPS_PTR[-1]) != SG_OPS_IDX.size:
raise RuntimeError(
"space-group operation pointers do not cover the index table"
)
if np.any(np.diff(SG_OPS_PTR) <= 0):
raise RuntimeError("every space group must have at least one operation")
if (
SG_OPS_IDX.size != 4425
or np.any(SG_OPS_IDX < 0)
or np.any(SG_OPS_IDX >= len(SYMM_OPS))
):
raise RuntimeError("space-group operation indices are malformed")
_validate_table()
@lru_cache(maxsize=1)
def _default_probabilities() -> dict[int, float]:
"""Return cached, validated default space-group sampling weights."""
return _validate_probabilities(SPACE_GROUP_PROBABILITIES)
def _validate_probabilities(probabilities: Mapping[int, float]) -> dict[int, float]:
"""Copy and validate finite nonnegative weights keyed by space group."""
if not isinstance(probabilities, Mapping):
raise TypeError("probabilities must be a mapping")
result: dict[int, float] = {}
for key, value in probabilities.items():
number = _validate_space_group(key)
if isinstance(value, bool) or not isinstance(value, Real):
raise TypeError("probability weights must be real numbers")
try:
weight = float(value)
except OverflowError as error:
raise ValueError(
"probability weights must be finite and nonnegative"
) from error
if not math.isfinite(weight) or weight < 0:
raise ValueError("probability weights must be finite and nonnegative")
result[number] = weight
return result
def _normalize_policy_probabilities(
probabilities: Mapping[Any, Any],
) -> dict[int, Any]:
"""Normalize canonical serialized group keys and detect key collisions."""
if not isinstance(probabilities, Mapping):
raise TypeError("probabilities must be a mapping")
normalized: dict[int, Any] = {}
for key, value in probabilities.items():
if isinstance(key, str):
if (
not key
or not key.isascii()
or not key.isdecimal()
or (len(key) > 1 and key.startswith("0"))
):
raise ValueError(
"serialized space-group keys must be canonical decimal strings"
)
number = int(key)
else:
number = key
number = _validate_space_group(number)
if number in normalized:
raise ValueError(
f"probabilities contain multiple keys for space group {number}"
)
normalized[number] = value
return normalized
def _validate_seed(seed: int | None) -> int | None:
"""Return a validated nonnegative seed, preserving public error categories."""
if seed is None:
return None
if isinstance(seed, bool) or not isinstance(seed, Integral):
raise TypeError("seed must be an integer or None")
value = int(seed)
if value < 0:
raise ValueError("seed must be nonnegative")
return value
[docs]
class SpaceGroupPolicy(BaseModel):
"""Immutable fixed or weighted-sampling rule for crystal space groups.
Construct policies with :meth:`fixed` or :meth:`sampled`. A sampled
policy stores an optional replacement prior and crystallographic filters;
its compatibility depends on the operation count required by a packing
configuration or a standalone :meth:`draw` call. Policies can be saved
and restored with Pydantic's JSON text, JSON-mode dictionary, or Python-mode
dictionary serialization routes. Restored model data accepts canonical
decimal string keys for ``probabilities`` and serialized
:class:`CrystalSystem` values; convenience sampling helpers continue to
require integer keys and enum values.
"""
model_config = ConfigDict(frozen=True, extra="forbid")
mode: Literal["fixed", "sampled"]
group: int | None = Field(default=None, strict=True)
probabilities: Mapping[int, float] | None = Field(default=None, repr=False)
crystal_system: CrystalSystem | None = None
sohncke_only: bool = Field(default=False, strict=True)
@field_validator("probabilities", mode="before")
@classmethod
def _copy_probabilities(cls, value: Any) -> Any:
"""Normalize, copy, and validate caller-owned prior mappings."""
if value is None:
return None
return _validate_probabilities(_normalize_policy_probabilities(value))
@field_validator("probabilities")
@classmethod
def _freeze_probabilities(
cls, value: Mapping[int, float] | None
) -> Mapping[int, float] | None:
"""Expose the copied prior through a read-only mapping."""
return None if value is None else MappingProxyType(dict(value))
@field_serializer("probabilities")
def _serialize_probabilities(
self, value: Mapping[int, float] | None
) -> dict[int, float] | None:
"""Return ordinary mapping data for Python and JSON serialization."""
return None if value is None else dict(value)
@field_validator("crystal_system", mode="before")
@classmethod
def _validate_crystal_system(cls, value: Any) -> Any:
if value is None or isinstance(value, CrystalSystem):
return value
if isinstance(value, str):
return CrystalSystem(value)
raise TypeError("crystal_system must be a CrystalSystem or None")
@model_validator(mode="after")
def _validate_state(self) -> SpaceGroupPolicy:
if not isinstance(self.sohncke_only, bool):
raise TypeError("sohncke_only must be a bool")
if self.mode == "fixed":
if self.group is None:
raise ValueError("fixed policies require a space-group number")
group = _validate_space_group(self.group)
if self.probabilities is not None or self.crystal_system is not None:
raise ValueError(
"fixed policies cannot include probabilities or crystal_system"
)
if self.sohncke_only and not is_sohncke_space_group(group):
raise ValueError(
"fixed group must be a Sohncke group when sohncke_only=True"
)
elif self.group is not None:
raise ValueError("sampled policies cannot specify a fixed group")
return self
[docs]
@classmethod
def fixed(cls, group: int, *, sohncke_only: bool = False) -> SpaceGroupPolicy:
"""Create a policy that always selects one compatible group.
The group number and optional handedness requirement are checked
immediately. Its operation count is checked when the policy enters a
packing configuration or a draw.
Parameters
----------
group : int
International space-group number in ``[1, 230]``.
sohncke_only : bool, default=False
Require the selected group to preserve molecular handedness.
Returns
-------
policy : SpaceGroupPolicy
Frozen fixed-group policy.
Raises
------
TypeError
If ``group`` is not a non-boolean integer or ``sohncke_only`` is
not a boolean.
ValueError
If ``group`` is outside ``[1, 230]`` or is not a Sohncke group when
``sohncke_only=True``.
"""
number = _validate_space_group(group)
if not isinstance(sohncke_only, bool):
raise TypeError("sohncke_only must be a bool")
return cls(mode="fixed", group=number, sohncke_only=sohncke_only)
[docs]
@classmethod
def sampled(
cls,
*,
probabilities: Mapping[int, float] | None = None,
crystal_system: CrystalSystem | None = None,
sohncke_only: bool = False,
) -> SpaceGroupPolicy:
"""Create a policy that samples compatible groups with replacement.
A custom mapping replaces the bundled CSD weights. Missing entries
have zero weight, and positive compatible weights are normalized when
resolving a draw or packing configuration.
Construction validates and copies the supplied weights. Compatibility
and positive remaining weight are checked when the policy enters a
packing configuration or a draw.
Parameters
----------
probabilities : Mapping[int, float], optional
Replacement relative weights keyed by group number.
crystal_system : CrystalSystem, optional
Restrict selection to one crystallographic system.
sohncke_only : bool, default=False
Keep only groups whose symmetry-generated copies preserve
molecular handedness.
Returns
-------
policy : SpaceGroupPolicy
Frozen sampled-group policy with a copied prior mapping.
Raises
------
TypeError
If ``probabilities`` is not a mapping, a key or weight has an
invalid type, ``crystal_system`` is not a ``CrystalSystem``, or
``sohncke_only`` is not a boolean.
ValueError
If a key is outside ``[1, 230]`` or a weight is negative or
nonfinite.
"""
if crystal_system is not None and not isinstance(crystal_system, CrystalSystem):
raise TypeError("crystal_system must be a CrystalSystem or None")
if not isinstance(sohncke_only, bool):
raise TypeError("sohncke_only must be a bool")
clean_prior = (
None if probabilities is None else _validate_probabilities(probabilities)
)
return cls(
mode="sampled",
probabilities=clean_prior,
crystal_system=crystal_system,
sohncke_only=sohncke_only,
)
[docs]
def draw(
self,
num_samples: int,
*,
num_operations: int,
seed: int | None = None,
device: Device = None,
) -> Tensor:
"""Draw compatible International space-group numbers with replacement.
Fixed policies repeat their group without advancing the random
generator.
Parameters
----------
num_samples : int
Positive number of groups to draw.
num_operations : int
Required number of symmetry operations.
seed : int, optional
Nonnegative seed for a local CPU ``torch.Generator``. Without a
seed, sampled policies consume the global CPU generator.
device : torch.device or str, optional
Device for the returned tensor.
Returns
-------
space_groups : torch.Tensor, shape ``[num_samples]``, dtype=torch.int32
Sampled International numbers. Fixed policies repeat their group.
Raises
------
TypeError
If either count is not a non-boolean integer or ``seed`` is not a
non-boolean integer or ``None``.
ValueError
If a count is not positive, ``seed`` is negative, a fixed group's
operation count does not match, or no compatible sampled group has
positive weight.
"""
samples = _validate_positive_integer(num_samples, "num_samples")
operations = _validate_positive_integer(num_operations, "num_operations")
seed = _validate_seed(seed)
groups, weights = _resolve_space_group_distribution(self, operations)
if self.mode == "fixed":
result = torch.full((samples,), groups[0], dtype=torch.int32)
else:
generator = None
if seed is not None:
generator = torch.Generator(device="cpu")
generator.manual_seed(seed)
selected = torch.multinomial(
torch.from_numpy(weights),
samples,
replacement=True,
generator=generator,
)
result = torch.tensor(groups, dtype=torch.int32)[selected]
return result.to(device=device) if device is not None else result
def _resolve_space_group_distribution(
policy: SpaceGroupPolicy, num_operations: int
) -> tuple[list[int], np.ndarray]:
"""Resolve ascending group IDs and normalized relative weights in float64."""
count = _validate_positive_integer(num_operations, "num_operations")
if policy.mode == "fixed":
if policy.group is None:
raise RuntimeError("fixed space-group policy has no group")
actual = get_space_group_operation_count(policy.group)
if actual != count:
raise ValueError(
f"fixed group {policy.group} has {actual} operations; {count} required"
)
return [policy.group], np.ones(1, dtype=np.float64)
candidates = _filter_candidates(count, policy.crystal_system, policy.sohncke_only)
prior = (
_default_probabilities()
if policy.probabilities is None
else policy.probabilities
)
weights = np.asarray(
[prior.get(number, 0.0) for number in candidates], dtype=np.float64
)
if weights.size == 0 or not np.isfinite(weights).all() or not np.any(weights > 0):
raise ValueError(
"at least one compatible space group must have a positive sampling weight"
)
weights /= weights.max()
weights /= math.fsum(weights.tolist())
return candidates, weights
[docs]
def csd_space_group_probabilities() -> dict[int, float]:
"""Return default space-group sampling weights as a fresh copy.
These relative weights were derived from the Cambridge Structural
Database (CSD); they are not probabilities until compatible groups are
selected and the remaining positive weights are normalized.
Returns
-------
probabilities : dict[int, float]
Weights for every International space-group number from 1 through 230,
including entries whose weight is zero. The returned mapping is
independent of library state.
Notes
-----
The bundled weights use space-group counts from the CCDC report
`CSD Space Group Statistics: Space Group Number Ordering (2026)
<https://www.ccdc.cam.ac.uk/media/CSD-Space-Group-Statistics-Space-Group-Number-Ordering-2026.pdf>`_.
"""
return _default_probabilities().copy()
[docs]
def get_space_group_operations(
space_group: int,
*,
dtype: torch.dtype = torch.float32,
device: Device = None,
) -> Tensor:
"""Return standard fractional operations for one space group.
Parameters
----------
space_group : int
International space-group number in ``[1, 230]``.
dtype : torch.dtype, default=torch.float32
Floating dtype for the returned operation tensor.
device : torch.device or str, optional
Device for the returned tensor. The bundled table itself remains on CPU.
Returns
-------
operations : torch.Tensor, shape ``[S, 3, 4]``
Fractional rotations in ``[..., :3]`` and translations in ``[..., 3]``.
For row-vector fractional coordinates, ``f_out = f @ R.T + t``.
Raises
------
TypeError
If ``space_group`` is not a non-boolean integer or ``dtype`` is not a
floating Torch dtype.
ValueError
If the International number is outside ``[1, 230]``.
Examples
--------
>>> operations = get_space_group_operations(2) # P-1 space group.
>>> print(operations) # Identity, then inversion.
tensor([[[ 1., 0., 0., 0.],
[ 0., 1., 0., 0.],
[ 0., 0., 1., 0.]],
<BLANKLINE>
[[-1., 0., 0., 0.],
[ 0., -1., 0., 0.],
[ 0., 0., -1., 0.]]])
"""
number = _validate_space_group(space_group)
if not isinstance(dtype, torch.dtype) or not dtype.is_floating_point:
raise TypeError("dtype must be a floating torch dtype")
start = int(SG_OPS_PTR[number - 1])
end = int(SG_OPS_PTR[number])
flat_rows = SYMM_OPS[SG_OPS_IDX[start:end]]
operations = torch.empty((end - start, 3, 4), dtype=dtype)
operations[:, :, :3] = torch.as_tensor(
flat_rows[:, :9].copy().reshape(-1, 3, 3), dtype=dtype
)
operations[:, :, 3] = torch.as_tensor(flat_rows[:, 9:12].copy(), dtype=dtype)
return operations.to(device=device) if device is not None else operations
[docs]
def get_space_group_operation_count(space_group: int) -> int:
"""Return the number of standard operations for a space group.
Parameters
----------
space_group : int
International space-group number in ``[1, 230]``.
Returns
-------
count : int
Number of operations in the pinned standard-setting table.
Raises
------
TypeError
If ``space_group`` is not a non-boolean integer.
ValueError
If the International number is outside ``[1, 230]``.
"""
number = _validate_space_group(space_group)
return int(SG_OPS_PTR[number] - SG_OPS_PTR[number - 1])
[docs]
def get_crystal_system(space_group: int) -> CrystalSystem:
"""Return the crystal system for an International space-group number.
Parameters
----------
space_group : int
International space-group number in ``[1, 230]``.
Returns
-------
crystal_system : CrystalSystem
One of the seven standard crystal systems.
Raises
------
TypeError
If ``space_group`` is not a non-boolean integer.
ValueError
If the International number is outside ``[1, 230]``.
"""
number = _validate_space_group(space_group)
for first, last, index in _CRYSTAL_SYSTEM_RANGES:
if first <= number <= last:
return tuple(CrystalSystem)[index]
raise RuntimeError("valid space group was not assigned to a crystal system")
[docs]
def is_sohncke_space_group(space_group: int) -> bool:
"""Return whether a group's symmetry preserves molecular handedness.
Parameters
----------
space_group : int
International space-group number in ``[1, 230]``.
Returns
-------
is_sohncke : bool
Whether all symmetry-generated copies preserve handedness.
Raises
------
TypeError
If ``space_group`` is not a non-boolean integer.
ValueError
If the International number is outside ``[1, 230]``.
"""
return _validate_space_group(space_group) in _SOHNCKE
def _filter_candidates(
num_operations: int,
crystal_system: CrystalSystem | None,
sohncke_only: bool,
) -> list[int]:
"""List groups matching operation count and optional crystallographic filters."""
count = _validate_positive_integer(num_operations, "num_operations")
if crystal_system is not None and not isinstance(crystal_system, CrystalSystem):
raise TypeError("crystal_system must be a CrystalSystem or None")
if not isinstance(sohncke_only, bool):
raise TypeError("sohncke_only must be a bool")
return [
number
for number in range(1, 231)
if get_space_group_operation_count(number) == count
and (crystal_system is None or get_crystal_system(number) is crystal_system)
and (not sohncke_only or number in _SOHNCKE)
]
[docs]
def get_space_group_candidates(
num_operations: int,
*,
crystal_system: CrystalSystem | None = None,
sohncke_only: bool = False,
) -> Tensor:
"""Return space-group numbers with a requested operation count.
Parameters
----------
num_operations : int
Positive required number of symmetry operations.
crystal_system : CrystalSystem, optional
Restrict results to one crystal system.
sohncke_only : bool, default=False
Keep only groups whose symmetry-generated copies preserve handedness.
Returns
-------
candidates : torch.Tensor, shape ``[K]``, dtype=torch.int32
Compatible International numbers in ascending order; ``K`` may be zero.
Raises
------
TypeError
If ``num_operations`` is not a non-boolean integer, or a filter has
the wrong type.
ValueError
If ``num_operations`` is not positive.
"""
return torch.tensor(
_filter_candidates(num_operations, crystal_system, sohncke_only),
dtype=torch.int32,
)
[docs]
def sample_space_groups(
num_samples: int,
num_operations: int,
*,
probabilities: Mapping[int, float] | None = None,
crystal_system: CrystalSystem | None = None,
sohncke_only: bool = False,
seed: int | None = None,
device: Device = None,
) -> Tensor:
"""Sample compatible International space-group numbers with replacement.
A supplied ``probabilities`` mapping replaces the default relative
sampling weights. Missing group entries have zero weight. After removing
incompatible groups, the remaining weights determine relative sampling
probabilities.
Parameters
----------
num_samples : int
Number of samples to draw; must be positive.
num_operations : int
Required number of symmetry operations.
probabilities : Mapping[int, float], optional
Replacement relative weights keyed by group number; values must be
finite and nonnegative.
crystal_system : CrystalSystem, optional
Restrict the compatible groups to one crystal system.
sohncke_only : bool, default=False
Use only groups whose symmetry-generated copies preserve molecular
handedness, such as for chiral molecules.
seed : int, optional
Nonnegative seed for a local CPU ``torch.Generator``.
device : torch.device or str, optional
Device for the returned int32 tensor.
Returns
-------
space_groups : torch.Tensor, shape ``[num_samples]``, dtype=torch.int32
Sampled International numbers.
Raises
------
TypeError
If the prior, filters, or integer arguments have invalid types.
ValueError
If no compatible group has positive weight or ``seed`` is negative.
Examples
--------
>>> groups = sample_space_groups(4, 1, seed=7)
>>> groups.dtype
torch.int32
"""
samples = _validate_positive_integer(num_samples, "num_samples")
seed = _validate_seed(seed)
policy = SpaceGroupPolicy.sampled(
probabilities=probabilities,
crystal_system=crystal_system,
sohncke_only=sohncke_only,
)
return policy.draw(samples, num_operations=num_operations, seed=seed, device=device)