BaseGrandCanonicalMonteCarloSampler

class grandfep.sampler.BaseGrandCanonicalMonteCarloSampler(system, topology, temperature, collision_rate, timestep, log, platform=<openmm.openmm.Platform; proxy of <Swig Object of type 'OpenMM::Platform *'> >, water_resname='HOH', water_O_name='O')

Bases: object

Base class for Grand Canonical Monte Carlo (GCMC) sampling.

This class provides a flexible framework for customizing OpenMM forces so that water molecules can be alchemically inserted (ghost → real) or deleted (real → ghost). Each water is assigned two properties:

  • is_real:

    • 1.0 : real water

    • 0.0 : ghost water.

  • is_switching:

    • 1.0 for the switching water (used for NEQ insertion/deletion)

    • 0.0 for all other waters.

The last water in the system is selected as the switching water (is_real=1, is_switching=1). During an insertion or deletion attempt, this water is swapped (coordinate and velocity) with a ghost or real water, enabling NEQ perturbation moves.

vdW interactions are handled via self.custom_nonbonded_force (openmm.CustomNonbondedForce), where per-particle parameters is_real and is_switching interact with the global parameter lambda_gc_vdw.

Electrostatic interactions are handled by self.nonbonded_force (openmm.NonbondedForce). Ghost waters are given zero charge, and switching waters use ParticleParameterOffset with a global parameter lambda_gc_coulomb.

Parameters:

  • system (System) – The OpenMM System object. Must include CustomNonbondedForce and NonbondedForce with appropriate per-particle parameters and global parameter definitions.

  • topology (Topology) – The OpenMM Topology object. Must contain water molecules with the specified residue and atom names.

  • temperature (Quantity) – The reference temperature for the system, with proper units (e.g., kelvin).

  • collision_rate (Quantity) – The collision rate (friction) for the Langevin integrator, with time units.

  • timestep (Quantity) – The timestep for the integrator, with time units (e.g., femtoseconds).

  • log (Union[str, Path]) – Path to the log file. This file will be opened in append mode.

  • platform (Platform) – The OpenMM computational platform to use. Default is CUDA.

  • water_resname (str) – The residue name of water in the topology. Default is ‘HOH’.

  • water_O_name (str) – The atom name of oxygen in water. Default is ‘O’.

logger
Type:

logging.Logger

compound_integrator

2 integrators in this attribute. The 1st one is for Canonical simulation, the 2nd one is for non-equilibirum insertion/deletion.

Type:

openmm.CompoundIntegrator

simulation

simulation ties together Topology, System, Integrator, and Context in this sampler.

Type:

app.Simulation

temperature

The reference temperature for the system, with proper units (e.g., kelvin).

Type:

unit.Quantity

kBT

k_B * T, with unit.

Type:

unit.Quantity

topology

The OpenMM Topology object. All the res_name, atom_index, atom_name, etc. are in this topology.

Type:

app.Topology

Adam_box

Adam value, considering the whole simulation box and all water molecules.

Type:

unit.Quantity

Adam_GCMC

Adam value, considering the selected sphere and water molecules in the sphere.

Type:

unit.Quantity

ghost_list

A list of residue indices of water that are set to ghost. Should only be modified with set_ghost_list(), and get by get_ghost_list().

Type:

list

water_res_2_atom

A dictionary of residue index to a list of atom indices of water.

Type:

dict

water_res_2_O

A dictionary of residue index to a list of atom indices of water oxygen.

Type:

dict

switching_water

The residue index of the switching water. The switching water will be set as the last water during initialization. It should not be changed during the simulation, as the ParticleParameterOffset can not be updated in NonbondedForce.

Type:

int

num_of_points_water

The number of points in the water model. 3 for TIP3P, 4 for OPC.

Type:

int

custom_nonbonded_force

This force handles vdW. It has PerParticleParameter is_real and is_switching to control real/ghost and switching/non-switching. It also has a global parameter lambda_gc_vdw to control the switching water.

Type:

openmm.CustomNonbondedForce

nonbonded_force

This force handles Coulomb. The switching water has ParticleParameterOffset with global parameter lambda_gc_coulomb to control the switching water.

Type:

openmm.NonbondedForce

wat_params

A dictionary to track the nonbonded parameter of water. The keys are “charge”, “sigma”, “epsilon”, The values are a list of parameters with unit.

Type:

dict

system_type

The type of the system. Can be Amber, Charmm or Hybrid depending on the system and energy expression in the given CustomNonbondedForce.

Type:

str

check_ghost_list()

Loop over all water particles in the system to validate that self.ghost_list correctly reflects the current ghost and switching water configuration.

  • Ghost water:

    1. is_real = 0.0 and is_switching = 0.0 in self.custom_nonbonded_force

    2. Charge = 0.0 in self.nonbonded_force

  • Real and not switching water:

    1. is_real = 1.0 in self.custom_nonbonded_force

    2. Charge = Proper_water_charge in self.nonbonded_force

  • Switching water:

    1. is_real = 1.0 in self.custom_nonbonded_force

    2. Charge = 0.0 in self.nonbonded_force

The switching water should not be present in self.ghost_list.

Raises:

ValueError – If any condition for ghost, real, or switching water is violated.

Return type:

None

check_switching()

Loop over all water particles in the system to make sure the one water given by self.switching_water is the only one that is switching.

  • Switching water:

    1. is_real = 1.0 and is_switching = 1.0 in self.custom_nonbonded_force

    2. Charge = 0.0 in self.nonbonded_force (ParticleParameters)

    3. chargeScale = proper_water_charge in ParticleParameterOffsets

  • Non-switching waters:

    1. is_switching = 0.0 in self.custom_nonbonded_force

    2. No ParticleParameterOffsets in self.nonbonded_force

Raises:

ValueError – If any switching or non-switching water fails to meet the expected criteria.

Return type:

None

get_ghost_list(check_system=False)

Get a copy of the current ghost water list.

If check_system is True, self.check_ghost_list will be called to validate the consistency of self.ghost_list with self.custom_nonbonded_force and self.nonbonded_force. If the validation fails, a ValueError will be raised.

Parameters:

check_system (bool) – If True, self.check_ghost_list() will be called to perform consistency checks in the system forces to ensure that the ghost list is correct. Default is False.

Returns:

A copy of self.ghost_list, which contains the residue indices of ghost waters.

Return type:

list

get_particle_parameter_index_cust_nb_force()

Get the indices of is_real and is_switching parameters in the perParticleParameters of self.custom_nonbonded_force.

Returns:

A tuple (is_real_index, is_switching_index) indicating the indices of the corresponding parameters in self.custom_nonbonded_force.getPerParticleParameterName(i).

Return type:

tuple of int

get_particle_parameter_offset_dict()

Retrieve all ParticleParameterOffset entries from self.nonbonded_force.

Returns:

A dictionary mapping atom indices to their corresponding ParticleParameterOffset data.

The key is the atom index. Each value is a list with the following structure: [ param_offset_index, global_parameter_name, atom_index, chargeScale, sigmaScale, epsilonScale ]

Return type:

dict

set_ghost_list(ghost_list, check_system=True)

Update the water residues in ghost_list to ghost.

If check_system is True, self.check_ghost_list will be called to validate the consistency of self.ghost_list with self.custom_nonbonded_force and self.nonbonded_force. If the validation fails, a ValueError will be raised.

Parameters:

  • ghost_list (list) – A list of residue indices (integers) that should be marked as ghost waters.

  • check_system (bool, optional) – If True, perform validation to ensure the internal force parameters are consistent with the updated ghost_list. Default is True.

Return type:

None