nvalchemi.csp.packer.OverlapReliefConfig#

class nvalchemi.csp.packer.OverlapReliefConfig(*, z, z_prime, batch_size, max_candidates='auto', max_steps_per_candidate=500, convergence_check_interval=10, overlap_tolerance=0.05, max_step=0.3, step_scale=0.12, cell_step_scale=0.01, max_cell_strain=0.003, volume_compression_scale=1e-05, min_cell_height=3.8, max_axis_ratio=10.0, cell_oversample_factor=1.5, cell_volume_range=None, cell_volume_scale_range=None, space_groups=<factory>)[source]#

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 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)
effective(**overrides)[source]#

Return a new configuration with validated overrides.

Parameters:

**overrides (Any) – Configuration field names and replacement values.

Returns:

A validated configuration containing the requested overrides.

Return type:

OverlapReliefConfig

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.

model_config = {'arbitrary_types_allowed': True, 'extra': 'forbid', 'frozen': True}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].