From 8fb80978fa951c6fb62e74731cb0b28e4919dc73 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Fri, 30 Aug 2019 18:21:41 +0200 Subject: [PATCH] Formatting and numpydoc style --- samples/grand_canonical.py | 16 +- samples/widom_insertion.py | 9 +- src/python/espressomd/reaction_ensemble.pyx | 197 ++++++++++---------- 3 files changed, 117 insertions(+), 105 deletions(-) diff --git a/samples/grand_canonical.py b/samples/grand_canonical.py index ca0f8c56b16..923bde2f5dd 100644 --- a/samples/grand_canonical.py +++ b/samples/grand_canonical.py @@ -17,9 +17,16 @@ # along with this program. If not, see . # """ -This example script performs a grand canonical simulation of a system in contact with a salt reservoir and ensures constant chemical potential. -It takes two command line arguments as input: 1) the reservoir salt concentration in units of 1/sigma^3 and 2) the excess chemical potential of the reservoir in units of kT. -The excess chemical potential of the reservoir needs to be determined prior to running the grand canonical simulation using the script called widom_insertion.py which simulates a part of the reservoir at the prescribed salt concentration. Be aware that the reservoir excess chemical potential depends on all interactions in the reservoir system. +This example script performs a grand canonical simulation of a system in contact +with a salt reservoir and ensures constant chemical potential. +It takes two command line arguments as input: 1) the reservoir salt concentration +in units of 1/sigma^3 and 2) the excess chemical potential of the reservoir in +units of kT. +The excess chemical potential of the reservoir needs to be determined prior to +running the grand canonical simulation using the script called widom_insertion.py +which simulates a part of the reservoir at the prescribed salt concentration. +Be aware that the reservoir excess chemical potential depends on all interactions +in the reservoir system. """ import numpy as np import argparse @@ -81,8 +88,7 @@ for type_1 in types: for type_2 in types: system.non_bonded_inter[type_1, type_2].lennard_jones.set_params( - epsilon=lj_eps, sigma=lj_sig, - cutoff=lj_cut, shift="auto") + epsilon=lj_eps, sigma=lj_sig, cutoff=lj_cut, shift="auto") RE = reaction_ensemble.ReactionEnsemble( temperature=temperature, exclusion_radius=2.0, seed=3) diff --git a/samples/widom_insertion.py b/samples/widom_insertion.py index 96b39c22076..da01deecfe2 100644 --- a/samples/widom_insertion.py +++ b/samples/widom_insertion.py @@ -17,8 +17,10 @@ # along with this program. If not, see . # """ -This example script measures the excess chemical potential of a charged WCA fluid via Widom's insertion method. -As input this script requires you to provide particle number density in units of 1/sigma^3. +This example script measures the excess chemical potential of a charged WCA +fluid via Widom's insertion method. +As input this script requires you to provide particle number density in units +of 1/sigma^3. """ import numpy as np import argparse @@ -79,8 +81,7 @@ for type_1 in types: for type_2 in types: system.non_bonded_inter[type_1, type_2].lennard_jones.set_params( - epsilon=lj_eps, sigma=lj_sig, - cutoff=lj_cut, shift="auto") + epsilon=lj_eps, sigma=lj_sig, cutoff=lj_cut, shift="auto") p3m = electrostatics.P3M(prefactor=2.0, accuracy=1e-3) system.actors.add(p3m) diff --git a/src/python/espressomd/reaction_ensemble.pyx b/src/python/espressomd/reaction_ensemble.pyx index be2034a8edb..01219a75329 100644 --- a/src/python/espressomd/reaction_ensemble.pyx +++ b/src/python/espressomd/reaction_ensemble.pyx @@ -13,10 +13,10 @@ class WangLandauHasConverged(Exception): cdef class ReactionAlgorithm: """ - This class provides the base class for Reaction Algorithms like the Reaction Ensemble algorithm, the Wang-Landau - Reaction Ensemble algorithm and the constant pH method. Initialize the - reaction algorithm by setting the standard pressure, temperature, and the - exclusion radius. + This class provides the base class for Reaction Algorithms like the Reaction + Ensemble algorithm, the Wang-Landau Reaction Ensemble algorithm and the + constant pH method. Initialize the reaction algorithm by setting the + standard pressure, temperature, and the exclusion radius. Note: When creating particles the velocities of the new particles are set according the Maxwell-Boltzmann distribution. In this step the mass of the @@ -26,16 +26,15 @@ cdef class ReactionAlgorithm: Parameters ---------- temperature : :obj:`float` - The temperature at which the reaction is performed. + The temperature at which the reaction is performed. exclusion_radius : :obj:`float` - Minimal distance from any particle, within which new - particle will not be inserted. This is useful to avoid - integrator failures if particles are too close and there - is a diverging repulsive interaction, or to prevent two - oppositely charged particles from being placed on top of - each other. The Boltzmann factor :math:`\exp(-\\beta - E)` gives these configurations a small contribution to - the partition function, therefore they can be neglected. + Minimal distance from any particle, within which new particle will not + be inserted. This is useful to avoid integrator failures if particles + are too close and there is a diverging repulsive interaction, or to + prevent two oppositely charged particles from being placed on top of + each other. The Boltzmann factor :math:`\exp(-\\beta E)` gives these + configurations a small contribution to the partition function, + therefore they can be neglected. """ cdef object _params cdef CReactionAlgorithm * RE @@ -47,8 +46,7 @@ cdef class ReactionAlgorithm: return "temperature", "exclusion_radius", "seed" def _set_params_in_es_core(self): - deref(self.RE).temperature = self._params[ - "temperature"] + deref(self.RE).temperature = self._params["temperature"] # setting a volume is a side effect, sets the default volume of the # reaction ensemble as the volume of the cuboid simulation box. this # volume can be altered by the command "reaction ensemble volume @@ -57,8 +55,7 @@ cdef class ReactionAlgorithm: # only contained in the volume of the cylinder) if(deref(self.RE).volume < 0): deref(self.RE).set_cuboid_reaction_ensemble_volume() - deref(self.RE).exclusion_radius = self._params[ - "exclusion_radius"] + deref(self.RE).exclusion_radius = self._params["exclusion_radius"] def set_cylindrical_constraint_in_z_direction(self, center_x, center_y, radius_of_cylinder): @@ -70,11 +67,11 @@ cdef class ReactionAlgorithm: Parameters ---------- center_x : :obj:`float` - x coordinate of center of the cylinder. + x coordinate of center of the cylinder. center_y : :obj:`float` - y coordinate of center of the cylinder. + y coordinate of center of the cylinder. radius_of_cylinder : :obj:`float` - radius of the cylinder + radius of the cylinder """ deref(self.RE).cyl_x = center_x @@ -135,14 +132,14 @@ cdef class ReactionAlgorithm: """ Sets the particle type for non-interacting particles. Default value: 100. - This is used to temporarily hide - particles during a reaction trial move, if they are to be deleted after - the move is accepted. - Please change this value if you intend to use the type 100 for some other - particle types with interactions. Please also note that particles in the current - implementation of the Reaction Ensemble are only hidden with respect to - Lennard-Jones and Coulomb interactions. Hiding of other interactions, - for example a magnetic, needs to be implemented in the code. + This is used to temporarily hide particles during a reaction trial + move, if they are to be deleted after the move is accepted. Please + change this value if you intend to use the type 100 for some other + particle types with interactions. Please also note that particles + in the current implementation of the Reaction Ensemble are only + hidden with respect to Lennard-Jones and Coulomb interactions. Hiding + of other interactions, for example a magnetic, needs to be implemented + in the code. """ deref(self.RE).non_interacting_type = non_interacting_type @@ -160,24 +157,22 @@ cdef class ReactionAlgorithm: Parameters ---------- gamma : :obj:`float` - Equilibrium constant of the reaction, :math:`\gamma` - (see the User guide, section 6.6 for the definition and further details). + Equilibrium constant of the reaction, :math:`\gamma` (see the User + guide, section 6.6 for the definition and further details). reactant_types : list of :obj:`int` - List of particle types of reactants in the reaction. + List of particle types of reactants in the reaction. reactant_coefficients : list - List of stoichiometric coefficients of the - reactants in the same order as the list of - their types. + List of stoichiometric coefficients of the reactants in the same + order as the list of their types. product_types : list - List of particle types of products in the reaction. + List of particle types of products in the reaction. product_coefficients : list - List of stoichiometric coefficients of - products of the reaction in the same order as - the list of their types + List of stoichiometric coefficients of products of the reaction in + the same order as the list of their types default_charges : dictionary - A dictionary of default charges for types that occur in the provided reaction. + A dictionary of default charges for types that occur in the provided reaction. check_for_electroneutrality : Boolean - Check for electroneutrality of the given reaction if True. + Check for electroneutrality of the given reaction if True. """ self._params["check_for_electroneutrality"] = True @@ -267,7 +262,7 @@ cdef class ReactionAlgorithm: Parameters ---------- reaction_steps : :obj:`int`, optional - The number of reactions to be performed at once, defaults to 1. + The number of reactions to be performed at once, defaults to 1. """ deref(self.RE).do_reaction(int(reaction_steps)) @@ -275,10 +270,11 @@ cdef class ReactionAlgorithm: def displacement_mc_move_for_particles_of_type(self, type_mc, particle_number_to_be_changed=1): """ - Performs a displacement Monte Carlo move for particles of given type. New positions - of the displaced particles are chosen from the whole box with a uniform probability distribution. - If there are multiple types, that are being moved in a simulation, they should be moved in a - random order to avoid artefacts. + Performs a displacement Monte Carlo move for particles of given type. + New positions of the displaced particles are chosen from the whole box + with a uniform probability distribution. If there are multiple types, + that are being moved in a simulation, they should be moved in a random + order to avoid artefacts. Parameters ---------- @@ -317,8 +313,12 @@ cdef class ReactionAlgorithm: for i in range(deref(self.RE).reactions[single_reaction_i].product_types.size()): product_coefficients.append( deref(self.RE).reactions[single_reaction_i].product_coefficients[i]) - reaction = {"reactant_coefficients": reactant_coefficients, "reactant_types": reactant_types, "product_types": product_types, "product_coefficients": - product_coefficients, "reactant_types": reactant_types, "gamma": deref(self.RE).reactions[single_reaction_i].gamma} + reaction = {"reactant_coefficients": reactant_coefficients, + "reactant_types": reactant_types, + "product_types": product_types, + "product_coefficients": product_coefficients, + "reactant_types": reactant_types, + "gamma": deref(self.RE).reactions[single_reaction_i].gamma} reactions.append(reaction) return {"reactions": reactions, "temperature": deref(self.RE).temperature, "exclusion_radius": deref(self.RE).exclusion_radius} @@ -434,11 +434,12 @@ cdef class WangLandauReactionEnsemble(ReactionAlgorithm): def reaction(self, reaction_steps=1): """ - Performs reaction_steps reactions. Sets the number of reaction steps which are - performed at once. Do not use too many reaction steps - steps consecutively without having conformation - changing steps in between (especially important for the Wang-Landau reaction ensemble). Providing a number for the parameter reaction steps reduces the need for the interpreter to be - called between consecutive reactions. + Performs reaction_steps reactions. Sets the number of reaction steps + which are performed at once. Do not use too many reaction steps steps + consecutively without having conformation changing steps in between + (especially important for the Wang-Landau reaction ensemble). Providing + a number for the parameter reaction steps reduces the need for the + interpreter to be called between consecutive reactions. """ status_wang_landau = deref( @@ -455,14 +456,13 @@ cdef class WangLandauReactionEnsemble(ReactionAlgorithm): Parameters ---------- associated_type : :obj:`int` - Particle type of the associated state of the reacting species. + Particle type of the associated state of the reacting species. min : :obj:`float` - Minimum value of the collective variable. + Minimum value of the collective variable. max : :obj:`float` - Maximum value of the collective variable. + Maximum value of the collective variable. corresponding_acid_types : list - List of the types of the version of the - species. + List of the types of the version of the species. """ for k in kwargs: @@ -498,23 +498,23 @@ cdef class WangLandauReactionEnsemble(ReactionAlgorithm): Parameters ---------- filename : :obj:`str` - Filename of the energy boundary file which provides the - potential energy boundaries (min E_pot, max E_pot) tabulated - for all degrees of association. Make sure to only list the - degrees of association which are used by the degree of - association collective variable within this file. The energy - boundary file can be created in a preliminary energy run. By - the help of the functions - :meth:`update_maximum_and_minimum_energies_at_current_state` - and :meth:`write_out_preliminary_energy_run_results`. This - file has to be obtained before being able to run a - simulation with the energy as collective variable. + Filename of the energy boundary file which provides the + potential energy boundaries (min E_pot, max E_pot) tabulated + for all degrees of association. Make sure to only list the + degrees of association which are used by the degree of + association collective variable within this file. The energy + boundary file can be created in a preliminary energy run. By + the help of the functions + :meth:`update_maximum_and_minimum_energies_at_current_state` + and :meth:`write_out_preliminary_energy_run_results`. This + file has to be obtained before being able to run a + simulation with the energy as collective variable. delta : :obj:`float` - Provides the discretization of the potential energy range. Only - for small enough delta the results of the energy reweighted - averages are correct. If delta is chosen too big there are - discretization errors in the numerical integration which occurs - during the energy reweighting process. + Provides the discretization of the potential energy range. Only + for small enough delta the results of the energy reweighted + averages are correct. If delta is chosen too big there are + discretization errors in the numerical integration which occurs + during the energy reweighting process. """ for k in kwargs: @@ -546,25 +546,17 @@ cdef class WangLandauReactionEnsemble(ReactionAlgorithm): Parameters ---------- final_wang_landau_parameter : :obj:`float` - Sets the final Wang-Landau parameter, which is the Wang-Landau parameter after which the simulation should stop.). + Sets the final Wang-Landau parameter, which is the Wang-Landau + parameter after which the simulation should stop.). full_path_to_output_filename : :obj:`str` - Sets the path to the output file of the - Wang-Landau algorithm which contains the - Wang-Landau potential + Sets the path to the output file of the Wang-Landau algorithm which + contains the Wang-Landau potential do_not_sample_reaction_partition_function : :obj:`bool` - Avoids sampling the - Reaction ensemble partition - function in the Wang-Landau - algorithm. Therefore this - option makes all degrees of - association equally - probable. This option may - be used in the sweeping - mode of the reaction - ensemble, since the - reaction ensemble partition - function can be later added - analytically. + Avoids sampling the Reaction ensemble partition function in the + Wang-Landau algorithm. Therefore this option makes all degrees of + association equally probable. This option may be used in the + sweeping mode of the reaction ensemble, since the reaction ensemble + partition function can be later added analytically. """ for k in kwargs: @@ -638,10 +630,18 @@ cdef class WangLandauReactionEnsemble(ReactionAlgorithm): def displacement_mc_move_for_particles_of_type(self, type_mc, particle_number_to_be_changed=1): """ - Performs an MC (Monte Carlo) move for particle_number_to_be_changed particle of type type_mc. Positions for the particles are drawn uniformly random within the box. The command takes into account the Wang-Landau terms in the acceptance probability. - If there are multiple types, that - need to be moved, make sure to move them in a random order to avoid - artefacts. For the Wang-Landau algorithm in the case of energy reweighting you would also need to move the monomers of the polymer with special moves for the MC part. Those polymer configuration changing moves need to be implemented in the case of using Wang-Landau with energy reweighting and a polymer in the system. Polymer configuration changing moves had been implemented before but were removed from espresso. + Performs an MC (Monte Carlo) move for particle_number_to_be_changed + particle of type type_mc. Positions for the particles are drawn + uniformly random within the box. The command takes into account the + Wang-Landau terms in the acceptance probability. + If there are multiple types, that need to be moved, make sure to move + them in a random order to avoid artefacts. For the Wang-Landau algorithm + in the case of energy reweighting you would also need to move the + monomers of the polymer with special moves for the MC part. Those + polymer configuration changing moves need to be implemented in the + case of using Wang-Landau with energy reweighting and a polymer in the + system. Polymer configuration changing moves had been implemented + before but were removed from espresso. """ use_wang_landau = True @@ -651,7 +651,9 @@ cdef class WangLandauReactionEnsemble(ReactionAlgorithm): cdef class WidomInsertion(ReactionAlgorithm): """ - This class implements the Widom insertion method in the canonical ensemble for homogeneous systems, where the excess chemical potential is not depending on the location. + This class implements the Widom insertion method in the canonical ensemble + for homogeneous systems, where the excess chemical potential is not + depending on the location. """ @@ -693,7 +695,10 @@ cdef class WidomInsertion(ReactionAlgorithm): def measure_excess_chemical_potential(self, reaction_id=0): """ - Measures the excess chemical potential in a homogeneous system. Returns the excess chemical potential and the standard error for the excess chemical potential. It assumes that your samples are uncorrelated in estimating the standard error. + Measures the excess chemical potential in a homogeneous system. + Returns the excess chemical potential and the standard error for the + excess chemical potential. It assumes that your samples are + uncorrelated in estimating the standard error. """ return self.WidomInsertionPtr.get().measure_excess_chemical_potential(int(reaction_id))