NoneqGrandCanonicalMonteCarloSampler

class grandfep.sampler.NoneqGrandCanonicalMonteCarloSampler(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', position=None, chemical_potential=None, standard_volume=None, sphere_radius=Quantity(value=10.0, unit=angstrom), reference_atoms=None)

Bases: BaseGrandCanonicalMonteCarloSampler

Nonequilibrium Grand Canonical Monte Carlo (Noneq-GCMC) sampler.

In this class, GCMC is achieved by performing insertion/deletion in a nonequilibrium candidate Monte Carlo manner. The work value of the insertion/deletion will be used to evaluate the acceptance ratio. Insertion/deletion can either be performed in the whole box or in a sub-volume (active site) of the box. In an equilibrium sampling, when the water is free to move in/out of the sub-volume, I recommend alternating between GCMC and box.

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. Must have the correct boxVector. Only rectangular box is supported.

  • 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 appended 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’.

  • position (Quantity) – Initial position of the system. Need to be provided for box Vectors. Default is None.

  • chemical_potential – Chemical potential of the system. with units. Default is None.

  • standard_volume – Standard volume of a water molecule in the reservoir. with units. Default is None.

  • sphere_radius (Quantity) – Radius of the GCMC sphere. Default is 10.0 * unit.angstroms.

  • reference_atoms (list) – A list of atom indices in the topology that will be set as the center of the GCMC sphere. Default is None.

Additional Attributes

gc_countdict
Dictionary to keep track of the GCMC moves. The keys are:

  • current_move: (int) the current move number

  • move: (list) list of move numbers

  • insert_delete: (list) list of 0/1 for insertion/deletion

  • work: (list) list of work values. In the unit of kcal/mol

  • box_GCMC: (list) list of 0/1 for box/GCMC

  • N: (list) list of number of water molecules in the box or GCMC sub-volume

  • accept: (list) list of 0/1 for rejection/acceptance

chemical_potentialunit.Quantity

Chemical potential of the system.

standard_volumeunit.Quantity

Standard volume of a water molecule in the reservoir.

reference_atomslist

A list of atom indices in the topology that will be set as the center of the GCMC sphere.

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

deletion_move_GCMC()
deletion_move_box()
gcmc_move(box=0)
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

insertion_move_GCMC()
insertion_move_box(l_vdw_list, l_coulomb_list, n_prop)

Perform a non-equilibrium insertion. The vdw will be turned on first, followed by coulomb

Parameters:

  • l_vdw_list (list) – A list of lambda_gc_vdw value that defines the path of insertion

  • l_coulomb_list (list) – A list of lambda_gc_coulomb value that defines the path of insertion

  • n_prop (int) – Number of propergation step (equlibrium MD) between each lambda switching.

Returns:

  • positions (unit.Quantity) – Positions after this GCMC move.

  • velocities (unit.Quantity) – Velocities after this GCMC move.

  • work (unit.Quantity) – Work during the insertion process.

  • accept (bool) – Whether the insertion move was accepted.

random_place_water(state, res_index, sphere_center=None)

Shift the coordinate+orientation of a water molecule to a random place. If the center is None, a random position in the box will be selected. If the center is not None, a randomed position in the GCMC sphere will be selected.

Parameters:

  • state (openmm.State) – The current state of the simulation context. The positions will be read from this state.

  • res_index (int) – The residue index of the water molecule to be shifted.

  • sphere_center (unit.Quantity) – The center of the GCMC sphere. If None, a random position in the box will be selected. Default is None.

Return type:

Quantity

Returns:

  • positions (unit.Quantity) – The new positions with the water molecule shifted.

  • velocities (unit.Quantity) – The new velocities with the water molecule shifted.

report(write_dcd=False)

Report the GC moves and write trajectory if needed. :type write_dcd: :param write_dcd: :return:

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

update_gc_count(insert_delete, work, box_GCMC, n_water, accept)

Update the internal gc_count dictionary that tracks GCMC insertion/deletion statistics.

Parameters:

  • insert_delete (int) – Indicator for the type of move: 0 for insertion, 1 for deletion.

  • work (unit.Quantity) – Work value (e.g., from nonequilibrium switching), with units. The value in kcal/mol will be recorded.

  • box_GCMC (int) – Region type indicator: 0 for the whole simulation box, 1 for a GCMC sub-volume.

  • n_water (int) – Number of water molecules in the whole box or in the GCMC sub-volume, depending on box_GCMC.

  • accept (int) – Indicator of whether the move was accepted: 1 for accepted, 0 for rejected.

Return type:

None