局部溶剂壳（Local Solvation）
Group: Organic | Class: LocalSolvationCard
What the card does
Local Solvation 在选中原子周围插入一批溶剂分子，用来补充离子水合壳、局部极性环境、溶质附近初始溶剂排布等候选构型。它只生成几何初态，不做力场或 DFT 优化，也不保证得到平衡溶剂化数或平衡取向。
这张卡保留输入结构，并追加溶剂原子；碰撞检查只负责排除明显短接触。Auto 会根据溶剂是否为一水分子以及中心元素是否包含内置离子来解析实际放置模式。卡片首帧预览会显示中心数、溶剂分子式、解析后的模式和真正采用的碰撞规则。
Example workflow
Scenario: The first hydration shell of an ion is missing
A Ca-containing training set is almost entirely dry and gives abnormal Ca-O interactions in water. Select Ca centers and insert 4-8 water molecules to propose hydration shells, then apply geometry checks and DFT relaxation before using them as labels.
参数设置：中心选择“按元素”并填 Ca，放置模式选“自动识别溶剂 / 离子”，每个输出放 6 个水分子，统一最小距离可先设为 0.8 Å，打开固定种子。
在 ion-water 模式下，Ca 第一配位壳的 O 原子距离来自内置 2.30–2.60 Å 区间；界面上的“备用质心壳层”只在该离子的内置配位数填满之后使用。不要把备用壳层误认为第一壳 Ca–O 距离。
Inspect Ca-O distances, short nonbonded H-H/O-H contacts, and whether the shell remains physically meaningful after DFT relaxation.
Parameters
Solvent input
Solvent XYZ（solvent_xyz）
str, default a three-atom water XYZ block. The parameter stores molecule text rather than a path, allowing card JSON to reproduce the input without the original file.
Independent outputs per input（structures）
int, default 1. Independent solvated variants per input.
Solvent molecules per output（solvent_count）
int，默认 6。每个输出结构插入多少个溶剂分子。离子第一壳通常从 4–8 开始；大分子局部溶剂环境再按中心原子数量扩大。
Placement profile（sampling_mode）
str，默认 auto。可选项：
auto：水 + 内置离子中心时解析为ion-water；只有水时解析为water；其他溶剂解析为general。general：在备用质心壳层内随机放置和取向。water：在备用质心壳层内放置水，并让 O→H 中点的方向大致背离局部中心。ion-water：内置离子的前若干个水使用元素专属 ion–O 区间并让 H 侧背离离子；达到内置配位数后回到备用质心壳层。loose/dense：主要改变默认碰撞半径缩放；它们不会自动改写界面中的备用壳层数值。
Center selection
Solvation centers（center_mode）
str, default all. One of all, elements, indices, or z_range; selects solvation centers.
Center Elements（center_elements）
str, empty by default; elements mode only. Example: Ca,Na,O.
Center Indices（center_indices）
str, empty by default; indices mode only. Uses 1-based indices and ranges such as 1,3,5-8.
Z Range（z_range）
tuple[float,float], default (0.0,0.0); z-range mode only. Selects centers by Cartesian z.
Geometric constraints
Fallback center-to-COM shell（shell）
tuple[float, float]，默认 (2.2, 4.5)，单位 Å。普通放置时是局部中心到溶剂质心的采样范围；ion-water 的第一配位壳不使用它，而是使用元素专属 ion–O 区间。外半径必须大于内半径。
Uniform minimum-distance override（min_distance）
float，默认 0。大于 0 时，所有试放溶剂原子与已有原子之间都使用同一个最小距离，且会忽略 collision_scale；等于 0 时才使用元素碰撞半径和 collision_scale。
Element-radius collision scale（collision_scale）
float，默认 0。等于 0 时使用解析后放置模式的内置半径缩放；大于 0 时覆盖模式默认值。仅在 min_distance=0 时生效。
Max Attempts（max_attempts）
int，默认 3000。每个输出结构全部溶剂分子共享的总尝试次数，不是“每个分子 3000 次”。
Strict Count（strict_count）
bool，默认 true。打开后，未插满 solvent_count 就失败；关闭后允许输出至少放入 1 个分子的部分结果。若一个分子都放不进去，即使关闭严格数量也会报错，避免输出带标签但实际未溶剂化的原结构。
Nonperiodic output
Auto Box（auto_box）
bool，默认 false。仅当输入没有有效 cell 时生效，打开后按输出坐标生成非周期显示盒。输入已有有效 cell（包括周期晶胞）时，卡片始终保留原 cell 和 PBC，不会因为这个选项把周期体系改成非周期体系。
Fixed Box Size（box_size）
float，默认 100.0，单位 Å。输入没有有效 cell 且 auto_box=False 时，输出会居中放入这个固定的非周期显示盒。
Box Padding（box_padding）
float, default 8.0 Å. Margin around coordinates when auto_box=True.
Min Box（min_box）
float, default 0.0 Å. Minimum cell length when automatic boxing is enabled.
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
First Ca hydration shell (six waters, fixed seed)
{
"class": "LocalSolvationCard",
"check_state": true,
"params": {
"structures": 1,
"solvent_count": 6,
"sampling_mode": "auto",
"center_mode": "elements",
"center_elements": "Ca",
"shell": [2.6, 3.4],
"min_distance": 0.8,
"strict_count": true,
"use_seed": true,
"seed": 42
}
}
Local aqueous surface environment (z-selected centers, partial output allowed)
{
"class": "LocalSolvationCard",
"check_state": true,
"params": {
"structures": 3,
"solvent_count": 12,
"sampling_mode": "water",
"center_mode": "z_range",
"z_range": [8.0, 14.0],
"shell": [2.4, 5.0],
"min_distance": 0.9,
"strict_count": false,
"auto_box": false,
"use_seed": true,
"seed": 7
}
}
Recommended combinations
Local Solvation->Geometry Filter: reject short contacts or abnormal cells after insertion.Local Solvation->FPS Filter: select representative solvated candidates for DFT.
Common questions
No centers selected: check that mode and its element, index, or z-range parameter match the input.
一直插不满目标数量：降低
solvent_count，放宽备用壳层，减小统一最小距离或碰撞缩放；如果目标是周期整盒溶剂，优先改用Solvent Box Fill。调了备用壳层但 Ca–O 距离没变化：
ion-water第一配位壳使用内置 ion–O 区间；卡片预览会列出实际范围。Obvious short contacts: increase collision separation, apply
Geometry Filter, and pre-relax with DFT or MD.
Output labels
SolvLocal(mode={mode},n={placed},sel={center_count})
Reproducibility
With use_seed, identical structures, order, parameters, centers, solvent text, and seed reproduce insertion. Changing any of those can change output.