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_sizeis the maximum number of candidates active at once. By default,max_candidates="auto"limits initialized trials to1000 * num_samplesfor each call. A positive integer sets a fixed cap; explicitNoneleaves 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_rangegives an absolute conventional-cell volume interval in cubic angstroms, whilecell_volume_scale_rangescales the formula-unit estimate byz.space_groupsis a fixed or sampledSpaceGroupPolicy. 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 to1000 * num_samples; a positive integer sets an absolute cap, andNoneleaves 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_primesymmetry 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:
Notes
Unknown fields are rejected by the same
extra='forbid'policy as direct construction. The retained policy is checked against the effectivez / z_primewithout 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].