ectoolkits.analysis.water module#

Water analysis

class ectoolkits.analysis.water.WaterOrientation(xyz: str, cell: Cell, surf1: ndarray, surf2: ndarray, **kwargs)[source]#

Bases: AnalysisBase

Analyze water density and orientation near surfaces using MDAnalysis. Inspired by WatAnalysis (github.com/ChiahsinChu/WatAnalysis) – credit to Jia-Xin Zhu.

Parameters:

  • xyz (str) – Path to the input XYZ trajectory file.

  • cell (ase.cell.Cell) – Simulation cell object defining periodic boundaries.

  • surf1 (np.ndarray) – Atom indices defining the first surface.

  • surf2 (np.ndarray) – Atom indices defining the second surface.

  • **kwargs (dict, optional) –

    Keyword arguments: - dt : float

    Time step between frames in the trajectory. Default is 1.0 ps.

    • verbosebool

      Verbosity level for AnalysisBase.

    • oh_cutofffloat

      Maximum O-H bond length to define water molecules. Default is 2 Å.

    • strictbool

      Strict handling of water molecules (identify water molecules again each timestep). Default is False.

    • originstr

      Where to place the coordinate system origin (“surf1” for the first surface or “center” for the electrolyte center). Default is “surf1”.

    • dzfloat

      Bin size for density profiles in Å. Default is 0.1.

    • oxygen_indiceslist[int]

      Indices of oxygen atoms. Default selects all atoms with name “O”.

    • hydrogen_indiceslist[int]

      Indices of hydrogen atoms. Default selects all atoms with name “H”.

cell#

Simulation cell object.

Type:

ase.cell.Cell

surf1_ag#

Atom group for the first surface.

Type:

AtomGroup

surf2_ag#

Atom group for the second surface.

Type:

AtomGroup

oh_cutoff#

Maximum O-H bond length.

Type:

float

strict#

Strict handling of water molecules.

Type:

bool

origin#

Coordinate system origin method.

Type:

str

dz#

Bin size for density profiles.

Type:

float

o_ag#

Atom group for oxygen atoms.

Type:

AtomGroup

h_ag#

Atom group for hydrogen atoms.

Type:

AtomGroup

water_dict#

Mapping of oxygen atom indices to two bonded hydrogen atom indices.

Type:

Dict[int, List[int]]

get_origin(z1: Union[float, ndarray], z2: Union[float, ndarray]) → ndarray[source]#

Determine the origin for the coordinate system.

Parameters:

  • z1 (float or np.ndarray) – Z-coordinate(s) of the first surface.

  • z2 (float or np.ndarray) – Z-coordinate(s) of the second surface.

Returns:

Z-coordinate(s) of the origin based on the specified reference (“center” or “surf1”). Defaults to an array of zeros if the origin is not recognized.

Return type:

np.ndarray

plot_density(ax: Axes, sym: bool = False) → None[source]#

Plot the density profile of water molecules.

Parameters:

  • ax (matplotlib.axes.Axes) – Axes object to plot on.

  • sym (bool, optional) – If True, plots the symmetrized profile. Default is False.

Return type:

None

plot_orientation(ax: Axes, sym: bool = False) → None[source]#

Plot the orientation profile of water molecules.

Parameters:

  • ax (matplotlib.axes.Axes) – Axes object to plot on.

  • sym (bool, optional) – If True, plots the symmetrized profile. Default is False.

Return type:

None

save_profiles(filename: str)[source]#

Save the z-axis, water density, and orientation profiles to a text file.

Parameters:

filename (str) – Path to the output file.

ectoolkits.analysis.water.bin_edges_to_grid(bin_edges: ndarray)[source]#

Convert bin edges to grid points at bin centers.

Parameters:

bin_edges (np.ndarray) – Array of bin edges.

Returns:

Array of grid points at bin centers.

Return type:

np.ndarray

ectoolkits.analysis.water.density(n, v, mol_mass: float)[source]#

Calculate density in g/cm³ from the number of particles.

Parameters:

  • n (int or array-like) – Number of particles.

  • v (float or array-like) – Volume in ų.

  • mol_mass (float) – Molar mass in g/mol.

Returns:

Density in g/cm³.

Return type:

float or array-like

ectoolkits.analysis.water.get_dipoles(h_positions: ndarray, o_positions: ndarray, water_dict: Dict[int, List[int]], cell: Cell) → ndarray[source]#

Calculate dipole moments for water molecules.

Parameters:

  • h_positions (np.ndarray) – Positions of hydrogen atoms.

  • o_positions (np.ndarray) – Positions of oxygen atoms.

  • water_dict (Dict[int, List[int]]) – Dictionary mapping oxygen atom indices to two bonded hydrogen atom indices.

  • cell (ase.cell.Cell) – Simulation cell object defining periodic boundaries.

Returns:

Array of dipole vectors for each oxygen atom. Entries are NaN for non-water oxygen atoms.

Return type:

np.ndarray

ectoolkits.analysis.water.identify_water_molecules(h_positions: ndarray, o_positions: ndarray, cell: Cell, oh_cutoff: float) → Dict[int, List[int]][source]#

Identify water molecules based on proximity of hydrogen and oxygen atoms.

Parameters:

  • h_positions (np.ndarray) – Positions of hydrogen atoms.

  • o_positions (np.ndarray) – Positions of oxygen atoms.

  • cell (ase.cell.Cell) – Simulation cell object defining periodic boundaries.

  • oh_cutoff (float) – Maximum O-H distance to consider as a bond.

Returns:

Dictionary mapping oxygen atom indices to lists of two bonded hydrogen atom indices.

Return type:

Dict[int, List[int]]

ectoolkits.analysis.water.water_density(n, v)[source]#

Calculate the density of water in g/cm³.

Parameters:

  • n (int or array-like) – Number of water molecules.

  • v (float or array-like) – Volume in ų.

Returns:

Density in g/cm³.

Return type:

float or array-like