Sampling API

Water Molecules

Water molecule representation for Monte Carlo sampling.

This module provides a WaterMolecule class that represents a TIP3P water molecule with position and orientation (Euler angles).

class q2m3.sampling.water_molecule.WaterMolecule(position, euler_angles=<factory>)

Bases: object

TIP3P water molecule with position and orientation.

The water molecule is defined by: - position: 3D coordinates of oxygen atom (center of molecule) - euler_angles: [roll, pitch, yaw] rotation in radians

Default orientation has hydrogens in the xy-plane, symmetric about x-axis.

Parameters:

• position (ndarray)

• euler_angles (ndarray)

position

Oxygen atom position in Angstrom

Type:

numpy.ndarray

euler_angles

Euler angles [roll, pitch, yaw] in radians

Type:

numpy.ndarray

property oxygen_position: ndarray

Return oxygen atom position (same as molecule position).

get_atom_coords()

Get coordinates of all three atoms (O, H1, H2).

Returns:

Array of shape (3, 3) with [O, H1, H2] coordinates in Angstrom.

Return type:

ndarray

get_charges()

Get TIP3P partial charges for all atoms.

Returns:

Array of shape (3,) with [O_charge, H1_charge, H2_charge].

Return type:

ndarray

copy()

Create an independent copy of this water molecule.

Return type:

WaterMolecule

Move Generation

Monte Carlo move generator for water molecules.

This module provides random translation and rotation moves for Monte Carlo sampling of water configurations.

class q2m3.sampling.mc_moves.MCMoveGenerator(translation_step=0.3, rotation_step=np.float64(0.2617993877991494))

Bases: object

Generator for Monte Carlo moves (translation and rotation).

Parameters:

• translation_step (float)

• rotation_step (float)

translation_step

Maximum translation in each direction (Angstrom)

Type:

float

rotation_step

Maximum rotation in each Euler angle (radians)

Type:

float

rotation_step: float = np.float64(0.2617993877991494)

propose_translation(water)

Propose a random translation move.

Parameters:

water (WaterMolecule) – Original water molecule

Returns:

New water molecule with translated position

Return type:

WaterMolecule

propose_rotation(water)

Propose a random rotation move.

Parameters:

water (WaterMolecule) – Original water molecule

Returns:

New water molecule with rotated orientation

Return type:

WaterMolecule

propose_move(water)

Propose either a translation or rotation move with equal probability.

Parameters:

water (WaterMolecule) – Original water molecule

Returns:

New water molecule with proposed move applied

Return type:

WaterMolecule

propose_move_for_system(waters)

Propose a move for one randomly selected water in the system.

Parameters:

waters (list[WaterMolecule]) – List of water molecules

Returns:

• new_waters: Copy of waters list with one water moved

• moved_index: Index of the water that was moved

Return type:

Tuple of (new_waters, moved_index)

Metropolis Sampling

Metropolis-Hastings sampler for solvation structure optimization.

This module provides a Metropolis-Hastings algorithm for sampling water configurations around a fixed solute molecule.

class q2m3.sampling.metropolis.MetropolisSampler(waters, energy_function, temperature=300.0, translation_step=0.3, rotation_step=np.float64(0.2617993877991494))

Bases: object

Metropolis-Hastings sampler for water configuration optimization.

Uses MC moves to sample configurations and accepts/rejects based on the Metropolis criterion with the given energy function.

Parameters:

• waters (list[WaterMolecule])

• energy_function (Callable[[list[WaterMolecule]], float])

• temperature (float)

• translation_step (float)

• rotation_step (float)

waters

List of WaterMolecule objects (MM region)

Type:

list[q2m3.sampling.water_molecule.WaterMolecule]

energy_function

Function that takes waters and returns energy in Hartree

Type:

collections.abc.Callable[[list[q2m3.sampling.water_molecule.WaterMolecule]], float]

temperature

Temperature in Kelvin for Boltzmann acceptance

Type:

float

translation_step

Maximum translation per move (Angstrom)

Type:

float

rotation_step

Maximum rotation per move (radians)

Type:

float

rotation_step: float = np.float64(0.2617993877991494)

run(n_steps)

Run Metropolis-Hastings sampling for n_steps.

Parameters:

n_steps (int) – Number of MC steps to run

Returns:

• energies: List of energies at each step

• acceptance_rate: Fraction of accepted moves

• best_energy: Lowest energy found

• best_config: Water configuration with lowest energy

Return type:

Dictionary containing

Force Field

TIP3P force field for water-water interactions.

This module provides energy calculations for TIP3P water molecules, including Lennard-Jones and Coulomb interactions.

class q2m3.sampling.mm_forcefield.TIP3PForceField(sigma_oo=3.15061, epsilon_oo=0.152)

Bases: object

TIP3P water model force field for MM energy calculations.

Computes: - Lennard-Jones energy (O-O interactions only) - Coulomb energy (all atom pairs)

All energies are returned in Hartree for compatibility with QM calculations.

Parameters:

• sigma_oo (float)

• epsilon_oo (float)

__init__(sigma_oo=3.15061, epsilon_oo=0.152)

Initialize TIP3P force field.

Parameters:

• sigma_oo (float) – LJ sigma parameter for O-O interaction (Angstrom)

• epsilon_oo (float) – LJ epsilon parameter for O-O interaction (kcal/mol)

compute_lj_energy(waters)

Compute Lennard-Jones energy between all water pairs.

Only O-O interactions are included (TIP3P convention).

Parameters:

waters (list[WaterMolecule]) – List of WaterMolecule objects

Returns:

Total LJ energy in Hartree

Return type:

float

compute_coulomb_energy(waters)

Compute Coulomb energy between all water pairs.

All atom-atom interactions between different molecules are included.

Parameters:

waters (list[WaterMolecule]) – List of WaterMolecule objects

Returns:

Total Coulomb energy in Hartree

Return type:

float

compute_mm_energy(waters)

Compute total MM energy (LJ + Coulomb) between all water pairs.

Parameters:

waters (list[WaterMolecule]) – List of WaterMolecule objects

Returns:

Total MM energy in Hartree

Return type:

float