# 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.
"""Validated configuration for tensor-based crystal packing."""
from __future__ import annotations
import math
from typing import Annotated, Any, Literal
from pydantic import BaseModel, ConfigDict, Field, model_validator
from nvalchemi.csp.symmetry import (
SpaceGroupPolicy,
_resolve_space_group_distribution,
get_space_group_operation_count,
)
[docs]
class OverlapReliefConfig(BaseModel):
"""Choose how many trial structures to sample, which crystal symmetries and cell
sizes to use, and when a trial is accepted.
``batch_size`` is the maximum number of candidates active at once. By
default, ``max_candidates="auto"`` limits initialized trials to
``1000 * num_samples`` for each call. A positive integer sets a fixed cap;
explicit ``None`` leaves the budget unlimited. A finite budget may return
fewer structures than requested. The output target and random generator
belong to the generating-function call.
Exactly one cell volume mode is required. ``cell_volume_range`` gives an
absolute conventional-cell volume interval in cubic angstroms, while
``cell_volume_scale_range`` scales the formula-unit estimate by ``z``.
``space_groups`` is a fixed or sampled :class:`SpaceGroupPolicy`. The
default sampled policy uses relative weights derived from the Cambridge
Structural Database (CSD). A custom prior replaces those weights.
Parameters
----------
z : int
Number of formula units in the conventional cell.
z_prime : int
Number of formula units in the asymmetric unit; must divide ``z``.
batch_size : int
Maximum number of candidates active at once.
max_candidates : int or {"auto"} or None, default="auto"
Maximum number of trial structures initialized during a call.
``"auto"`` resolves to ``1000 * num_samples``; a positive integer sets
an absolute cap, and ``None`` leaves the budget unlimited.
An explicit unlimited budget assumes reachable acceptance criteria and
can keep the search running without useful progress. Before a large or
unlimited run, use a short pre-flight with a finite candidate budget
and the intended starting-volume range, overlap tolerance, and
per-candidate relaxation limit. Inspect accepted versus generated
counts; low or zero acceptance can indicate an overly small starting
volume. Revisit the volume settings and repeat the pre-flight before
scaling up.
max_steps_per_candidate : int, default=500
Maximum relaxation updates for one candidate before it expires.
convergence_check_interval : int, default=10
Number of relaxation iterations between regular acceptance checks.
Checks also occur at iteration zero and at candidate expiry.
overlap_tolerance : float, default=0.05
Largest positive overlap allowed between atoms in different molecular
copies, in angstroms.
max_step : float, default=0.3
Upper bound in angstroms on the small-rotation estimate of per-atom
movement used to scale one rigid update. A finite rotation can move an
atom slightly farther.
step_scale : float, default=0.12
Scale applied to numerical clash-removal forces and torques; these are
not physical model forces.
cell_step_scale : float, default=0.01
Scale for cell-shape and excess-volume updates; zero disables them.
max_cell_strain : float, default=0.003
Limit on a cell update's strain and compression components.
volume_compression_scale : float, default=1.0e-5
Strength of compression when a cell exceeds its sampled reference
volume.
min_cell_height : float, default=3.8
Minimum perpendicular cell height for initial sampling, in angstroms.
Relaxation separately rejects proposed cells below 2.5 angstroms.
max_axis_ratio : float, default=10.0
Largest cell-axis length ratio allowed during initial sampling.
cell_oversample_factor : float, default=1.5
Multiplier for the number of initial cell trials.
cell_volume_range : tuple[float, float], optional
Inclusive initial conventional-cell volume range, in cubic angstroms.
cell_volume_scale_range : tuple[float, float], optional
Initial volume multipliers applied to formula-unit volume times ``z``.
Supply exactly one of the two volume ranges.
space_groups : SpaceGroupPolicy, default=SpaceGroupPolicy.sampled()
Fixed or sampled space-group selection. Its groups must have exactly
``z / z_prime`` symmetry operations. A sampled policy needs positive
compatible weight after filtering.
Examples
--------
Use a scale range with a finite candidate budget::
from nvalchemi.csp.symmetry import CrystalSystem, SpaceGroupPolicy
config = OverlapReliefConfig(
z=4,
z_prime=1,
batch_size=16,
max_candidates=64,
cell_volume_scale_range=(0.8, 1.2),
space_groups=SpaceGroupPolicy.sampled(
crystal_system=CrystalSystem.MONOCLINIC,
sohncke_only=True,
),
)
Derive a separately validated configuration for one call::
shorter_run = config.effective(max_steps_per_candidate=300)
"""
model_config = ConfigDict(frozen=True, extra="forbid", arbitrary_types_allowed=True)
z: int = Field(strict=True)
z_prime: int = Field(strict=True)
batch_size: int = Field(strict=True)
max_candidates: Annotated[int, Field(strict=True)] | Literal["auto"] | None = "auto"
max_steps_per_candidate: int = Field(default=500, strict=True)
convergence_check_interval: int = Field(default=10, strict=True)
overlap_tolerance: float = 0.05
max_step: float = 0.3
step_scale: float = 0.12
cell_step_scale: float = 0.01
max_cell_strain: float = 0.003
volume_compression_scale: float = 1.0e-5
min_cell_height: float = 3.8
max_axis_ratio: float = 10.0
cell_oversample_factor: float = 1.5
cell_volume_range: tuple[float, float] | None = None
cell_volume_scale_range: tuple[float, float] | None = None
space_groups: SpaceGroupPolicy = Field(default_factory=SpaceGroupPolicy.sampled)
@model_validator(mode="after")
def _validate_configuration(self) -> OverlapReliefConfig:
"""Validate coupled packing, sampling, and relaxation settings."""
for name in (
"z",
"z_prime",
"batch_size",
"max_steps_per_candidate",
"convergence_check_interval",
):
value = getattr(self, name)
if isinstance(value, bool) or value <= 0:
raise ValueError(f"{name} must be a positive integer")
if self.z % self.z_prime:
raise ValueError("z_prime must divide z")
if isinstance(self.max_candidates, int) and (
isinstance(self.max_candidates, bool) or self.max_candidates <= 0
):
raise ValueError(
"max_candidates must be a positive integer, 'auto', or None"
)
positive_controls = ("max_step", "min_cell_height")
for name in positive_controls:
value = getattr(self, name)
if not math.isfinite(value) or value <= 0:
raise ValueError(f"{name} must be finite and positive")
nonnegative_controls = (
"step_scale",
"cell_step_scale",
"max_cell_strain",
"volume_compression_scale",
"overlap_tolerance",
)
for name in nonnegative_controls:
value = getattr(self, name)
if not math.isfinite(value) or value < 0:
raise ValueError(f"{name} must be finite and nonnegative")
if not math.isfinite(self.max_axis_ratio) or self.max_axis_ratio < 1:
raise ValueError("max_axis_ratio must be finite and at least 1")
if (
not math.isfinite(self.cell_oversample_factor)
or self.cell_oversample_factor < 1
):
raise ValueError("cell_oversample_factor must be finite and at least 1")
if (self.cell_volume_range is None) == (self.cell_volume_scale_range is None):
raise ValueError(
"exactly one of cell_volume_range and cell_volume_scale_range is required"
)
for name in ("cell_volume_range", "cell_volume_scale_range"):
interval = getattr(self, name)
if interval is not None:
low, high = interval
if (
not math.isfinite(low)
or not math.isfinite(high)
or low <= 0
or high <= 0
or low > high
):
raise ValueError(
f"{name} must contain finite positive values in ascending order"
)
required_operations = self.z // self.z_prime
if self.space_groups.mode == "fixed":
if self.space_groups.group is None:
raise RuntimeError("fixed space-group policy has no group")
group = self.space_groups.group
actual_operations = get_space_group_operation_count(group)
if actual_operations != required_operations:
raise ValueError(
f"fixed space group {group} has {actual_operations} operations; "
f"z / z_prime requires {required_operations} "
f"(z={self.z}, z_prime={self.z_prime})"
)
else:
_resolve_space_group_distribution(self.space_groups, required_operations)
return self
[docs]
def effective(self, **overrides: Any) -> OverlapReliefConfig:
"""Return a new configuration with validated overrides.
Parameters
----------
**overrides : Any
Configuration field names and replacement values.
Returns
-------
OverlapReliefConfig
A validated configuration containing the requested overrides.
Notes
-----
Unknown fields are rejected by the same ``extra='forbid'`` policy as
direct construction. The retained policy is checked against the
effective ``z / z_prime`` without changing its weights.
"""
values = {name: getattr(self, name) for name in type(self).model_fields}
values.update(overrides)
return type(self).model_validate(values)