cemd.build.Splitter

class Splitter(system, coordinate=None, axis=2, gap_size=20.0, bonds_dict=None, keep_molecules=False, ionic_dict=None, _solution_blueprint=None, _padding=2.0, _vacuum=0.0, _has_solution=False)

Bases: BaseBuilder

Split a system along an axis and optionally add a solution.

A cut can sever real interatomic bonds. Bonds that exist explicitly in the system’s topology are dropped automatically. Contacts that are structure-bearing but carry no explicit bond – the Si-O framework under ClayFF/CSHFF, for instance – are found geometrically instead, from bonds_dict; use count_broken_bonds() or scan_broken_bonds() to choose where to cut, and repair=True to cap the dangling atoms left behind.

In a disordered solid there is often no plane that cuts no bond at all. With keep_molecules=True the cut follows the molecules instead of a plane: every covalent unit (explicit bonds plus the contacts of bonds_dict: a silicate chain with its O and H, a water molecule, a hydroxide…) moves as a whole, on the side holding most of its mass, and every isolated cation (Ca, Na…) goes to the side where it keeps most of its coordination shell (ionic_dict). No covalent bond is then broken, whatever the cut position; coordinate=None picks the position that cuts the fewest ionic contacts (best_coordinate()).

After split(), split_report gives the contacts measured as broken on the actual geometry, before vs. after the split.

Parameters:

systemAtomicSystem

The system to split.

coordinatefloat, optional

Position along axis at which to cut, as a projection on the axis unit vector. None uses best_coordinate().

axisint or str, default=2

Axis along which to split (‘x’/’y’/’z’ or 0/1/2).

gap_sizefloat, default=20.0

Width of the gap to open, in Å.

bonds_dictdict, optional

{(type_or_element, type_or_element): cutoff} used to detect severed contacts. Defaults to DEFAULT_BOND_CUTOFFS.

keep_moleculesbool, default=False

Move whole covalent units rather than a half-space (see above).

ionic_dictdict, optional

{(cation, anion): cutoff} coordination shells, types or elements. Defaults to DEFAULT_IONIC_CUTOFFS.

Examples

>>> # Simple split: cut at z=15, opening a 20 A gap there
>>> result = Splitter(system, coordinate=15.0, axis='z', gap_size=20.0).split()

>>> # Split with solution (fluent API)
>>> result = (Splitter(system, coordinate=15.0, axis='z', gap_size=30.0)
...           .add_solution(blueprint, padding=2.0)
...           .split())

>>> # Look for the least damaging cut, then split and cap what breaks
>>> splitter = Splitter(system, coordinate=0.0, axis='z', gap_size=20.0)
>>> scan = splitter.scan_broken_bonds(step=0.25)
>>> best = scan.loc[scan["n_broken"].idxmin(), "coordinate"]
>>> result = splitter.with_coordinate(best).split(repair=True)

>>> # Pore in a disordered solid: no covalent bond broken, cut placed
>>> # where it costs the fewest ionic contacts, liquid in the pore
>>> result = (Splitter(system, axis='z', gap_size=30.0, keep_molecules=True)
...           .add_solution(blueprint)
...           .split())

__init__(system, coordinate=None, axis=2, gap_size=20.0, bonds_dict=None, keep_molecules=False, ionic_dict=None, _solution_blueprint=None, _padding=2.0, _vacuum=0.0, _has_solution=False)

Methods

add_solution	Add a liquid solution in the gap.
best_coordinate	Cut position breaking the fewest bonds, then the fewest ionic contacts.
build	Alias for split(), to satisfy the BaseBuilder interface.
count_broken_bonds	Count the bonds a cut at coordinate would sever.
count_broken_ionic	Count the ionic contacts (ionic_dict) a cut would sever.
find_broken_bonds	Find the bonds a cut would sever, from the current geometry.
scan_broken_bonds	Count severed contacts across a range of cut positions.
side_mask	Atoms moved by the split (by position in system.atoms).
split	Execute the split and return the resulting AtomicSystem.
with_coordinate	Set the cutting position.

Attributes

axis
bonds_dict
coordinate
gap_size
ionic_dict
keep_molecules
repair_report
split_report
system