NoneqGrandCanonicalMonteCarloSamplerMPI

class grandfep.sampler.NoneqGrandCanonicalMonteCarloSamplerMPI(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: NoneqGrandCanonicalMonteCarloSampler

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

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