周期溶剂盒（Solvent Box Fill）

Group: Organic | Class: SolventBoxFillCard

What the card does

Solvent Box Fill 在已有周期性晶胞的整个 cell 中随机插入溶剂分子，适合从空盒、干结构或稀疏溶剂结构生成周期溶剂候选初态。输入可以没有原子，但必须有有限且非奇异的 cell，并且至少一个周期方向开启。

它解决的是“训练集缺少周期溶剂环境”的覆盖问题，不替代分子动力学平衡或量化优化。各模式下分子位置和整体取向都采用随机采样；water、loose、dense 主要改变默认碰撞半径缩放，并不会生成局部离子水合取向。

Example workflow

Scenario: The model has seen vacuum surfaces but no periodic solvent box

For an interface or solution NEP whose data are mostly dry surfaces and single adsorbates, begin from a periodic cell and insert a fixed or density-estimated solvent count to propose full-box initial states.

Parameters: count_mode="fixed", solvent_count=200, sampling_mode="auto", min_distance=0.8, max_attempts_per_solvent=500, and use_seed enabled.

Check whether the target count was reached, short contacts exist, molecules lie within the periodic cell, and pre-relaxation remains stable.

Parameters

Solvent input

Solvent XYZ（solvent_xyz）

str, default a three-atom water XYZ block. Stores molecule text, not a path.

Independent outputs per input（structures）

int, default 1. Independent box-fill variants per input.

Count control

Target amount（count_mode）

str，默认 fixed。可选 fixed、density。fixed 直接使用目标分子数；density 根据完整 cell 体积、溶剂分子质量、目标密度和数量乘数估算一个名义分子数。

Target solvent molecules（solvent_count）

int, default 100; fixed mode only.

Density（density）

float, default 1.0 g/cm³; density mode only.

Density count multiplier（fill_packing）

float，默认 1.0，范围 (0, 1]。count_mode="density" 时乘到名义纯溶剂分子数上；小于 1 会降低目标数量。大于 1 没有清楚的“填充比例”含义，因此程序不再静默截断，而是直接报错。

Warning

密度模式不会扣除宿主原子、已有溶剂或真空层占据的体积，也不会根据溶质质量反算最终溶液密度。对含表面、溶质或大块固体的 cell，它只是按完整 cell 体积给出的初始数量估计；请看卡片预览中的解析数量，再用 fill_packing 或固定数量修正。

Sampling and geometry constraints

Collision profile（sampling_mode）

str，默认 auto。可选 auto、general、water、loose、dense。auto 只根据溶剂分子是否恰好为 H₂O 解析成 water 或 general；整盒填充没有局部中心，因此不会进入 ion-water。这些配置主要控制 min_distance=0 时的默认元素半径缩放，分子整体取向始终是随机的。

Uniform minimum-distance override（min_distance）

float，默认 0。大于 0 时，所有试放溶剂原子与已有原子之间使用同一个最小距离，并忽略 collision_scale；等于 0 时使用元素碰撞半径。

Element-radius collision scale（collision_scale）

float，默认 0。等于 0 时使用碰撞配置的内置缩放；大于 0 时覆盖配置默认值。仅在 min_distance=0 时生效。

Max Attempts Per Solvent（max_attempts_per_solvent）

int，默认 500。总尝试上限是“该值 × 目标分子数”；若连续拒绝次数达到内部停滞阈值，也会提前停止。高密度盒子触顶时，优先检查目标数量和碰撞规则，再考虑增加它。

Strict Count（strict_count）

bool，默认 true。打开后，未插满目标数量就失败；关闭后允许输出至少放入 1 个分子的部分结果。若一个分子都放不进去，仍会报错，避免把未变化的输入标成“已填盒”。

Flexible solvent molecules

Flex Solvent（flex_solvent）

bool，默认 false。打开后复用“有机构象采样”的几何启发式拓扑生成溶剂构象池，再用于填盒。水没有可旋转单键，因此普通水盒不需要打开；打开后主要只增加高斯坐标噪声。

Flex Pool（flex_pool）

int, default 32. Size of the conformer pool for a flexible solvent.

Flex Torsion Range（flex_torsion_range）

tuple[float, float]，默认 (-180.0, 180.0)，单位 degree。柔性构象生成时附加的扭转角增量范围。

Flex Max Torsions（flex_max_torsions）

int, default 5. Maximum number of rotatable bonds perturbed in each flexible conformer.

Flex Gaussian Sigma（flex_gaussian_sigma）

float, default 0.03 Å. Coordinate noise added while generating flexible conformers.

Randomness

Use Seed（use_seed）

bool, default false. When enabled, identical input, parameters, and seed produce identical output.

Seed（seed）

int, default 0. Used when use_seed=True.

Recommended presets

Fixed-count water box (200 waters, fixed seed)

{
  "class": "SolventBoxFillCard",
  "check_state": true,
  "params": {
    "structures": 1,
    "count_mode": "fixed",
    "solvent_count": 200,
    "sampling_mode": "auto",
    "min_distance": 0.8,
    "max_attempts_per_solvent": 500,
    "strict_count": true,
    "use_seed": true,
    "seed": 42
  }
}

Density-based water box (partial output allowed)

{
  "class": "SolventBoxFillCard",
  "check_state": true,
  "params": {
    "structures": 3,
    "count_mode": "density",
    "density": 1.0,
    "fill_packing": 0.7,
    "sampling_mode": "water",
    "min_distance": 0.85,
    "max_attempts_per_solvent": 800,
    "strict_count": false,
    "use_seed": true,
    "seed": 7
  }
}

Recommended combinations

Solvent Box Fill -> Geometry Filter: reject short contacts and abnormal boxes.
Solvent Box Fill -> FPS Filter: reduce many initial boxes to representative DFT candidates.

Common questions

No valid periodic cell: use a nonsingular cell with periodicity, or choose Local Solvation for a nonperiodic local environment.
无法插满目标数量：降低固定数量或密度数量乘数，减小统一最小距离或元素半径缩放，增大 cell；也可以关闭严格数量先保留非零的部分结果。
按密度估算的数量不符合预期：数量由完整 cell 体积、溶剂分子质量、目标密度和数量乘数共同决定，不会扣除宿主占据体积。先检查 cell 单位、真空层、已有原子和 solvent_xyz。
想生成离子第一水合壳：改用 Local Solvation。整盒卡不会按离子元素选择 ion–O 距离或水分子取向。

Output labels

SolvBox(mode={mode},req={目标数},ok={实际放入数})

Reproducibility

With use_seed, identical input, order, parameters, and seed reproduce filling. In density mode, changing cell volume or solvent text changes the target count and output.