From e3e5ef75e7c55c59d169f3c9d9fc068f711c8305 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Tue, 30 Jul 2019 16:02:31 +0200 Subject: [PATCH 1/3] Cleanup documentation Apply numpydoc style (only one level of indentation for parameter descriptions, no single quote around parameter names, allowed values listed within curly braces), remove duplicated docstrings, use LaTeX math to display equations of constraints, fix broken Sphinx syntax (directives start with two dots, add missing links, etc.). --- src/python/espressomd/analyze.pyx | 7 +- src/python/espressomd/cellsystem.pyx | 63 +++-- src/python/espressomd/cluster_analysis.py | 5 +- src/python/espressomd/collision_detection.pyx | 53 ++-- src/python/espressomd/comfixed.py | 3 +- src/python/espressomd/constraints.py | 69 +++-- src/python/espressomd/electrokinetics.pyx | 42 +-- .../espressomd/electrostatic_extensions.pyx | 90 +++---- src/python/espressomd/electrostatics.pyx | 8 +- src/python/espressomd/interactions.pxd | 45 ++-- src/python/espressomd/interactions.pyx | 184 ++++++------- src/python/espressomd/lb.pyx | 8 +- .../espressomd/magnetostatic_extensions.pyx | 8 +- src/python/espressomd/magnetostatics.pyx | 12 +- src/python/espressomd/minimize_energy.pyx | 15 +- src/python/espressomd/pair_criteria.py | 12 +- src/python/espressomd/particle_data.pyx | 249 +++++++++--------- src/python/espressomd/shapes.py | 78 +++--- src/python/espressomd/system.pyx | 18 +- src/python/espressomd/thermostat.pyx | 15 +- .../espressomd/visualization_opengl.pyx | 202 +++++++------- 21 files changed, 589 insertions(+), 597 deletions(-) diff --git a/src/python/espressomd/analyze.pyx b/src/python/espressomd/analyze.pyx index e297830530a..05e0b0154a8 100644 --- a/src/python/espressomd/analyze.pyx +++ b/src/python/espressomd/analyze.pyx @@ -125,7 +125,8 @@ class Analysis: Parameters ---------- id : :obj:`int`, optional - Calculate distance to particle with :attr:`~espressomd.particle_data.ParticleHandle.id` `id`. + Calculate distance to particle with + :attr:`~espressomd.particle_data.ParticleHandle.id` `id`. pos : array of :obj:`float`, optional Calculate distance to position `pos`. @@ -1184,8 +1185,8 @@ class Analysis: Parameters ---------- - mode : :obj:`str` - One of ```read```, ```set``` or ```reset```. + mode : :obj:`str`, \{'read', 'set' or 'reset'\} + Mode. Vk1 : :obj:`float` Volume. Vk2 : :obj:`float` diff --git a/src/python/espressomd/cellsystem.pyx b/src/python/espressomd/cellsystem.pyx index 61dfda8596b..515bf0ff686 100644 --- a/src/python/espressomd/cellsystem.pyx +++ b/src/python/espressomd/cellsystem.pyx @@ -25,20 +25,18 @@ from espressomd.utils cimport handle_errors from espressomd.utils import is_valid_type cdef class CellSystem: - def set_domain_decomposition( - self, - use_verlet_lists=True, - fully_connected=[False, - False, - False]): + def set_domain_decomposition(self, use_verlet_lists=True, + fully_connected=[False, + False, + False]): """ Activates domain decomposition cell system. Parameters ---------- - 'use_verlet_lists' : :obj:`bool`, optional - Activates or deactivates the usage of Verlet lists - in the algorithm. + use_verlet_lists : :obj:`bool`, optional + Activates or deactivates the usage of Verlet lists + in the algorithm. """ @@ -56,9 +54,9 @@ cdef class CellSystem: Parameters ---------- - 'use_verlet_lists' : :obj:`bool`, optional - Activates or deactivates the usage of the Verlet - lists for this algorithm. + use_verlet_lists : :obj:`bool`, optional + Activates or deactivates the usage of the Verlet + lists for this algorithm. """ cell_structure.use_verlet_list = use_verlet_lists @@ -75,11 +73,11 @@ cdef class CellSystem: Parameters ---------- - 'n_layers': :obj:`int`, optional, positive - Sets the number of layers in the z-direction. - 'use_verlet_lists' : :obj:`bool`, optional - Activates or deactivates the usage of the Verlet - lists for this algorithm. + n_layers: :obj:`int`, optional, positive + Sets the number of layers in the z-direction. + use_verlet_lists : :obj:`bool`, optional + Activates or deactivates the usage of the Verlet + lists for this algorithm. """ cell_structure.use_verlet_list = use_verlet_lists @@ -192,8 +190,8 @@ cdef class CellSystem: Parameters ---------- global_flag : :obj:`bool` - If true, a global resorting is done, otherwise particles - are only exchanged between neighboring nodes. + If true, a global resorting is done, otherwise particles + are only exchanged between neighboring nodes. """ @@ -287,22 +285,23 @@ cdef class CellSystem: Parameters ----------- - 'min_skin' : :obj:`float` - Minimum skin to test. - 'max_skin' : :obj:`float` - Maximum skin. - 'tol' : :obj:`float` - Accuracy in skin to tune to. - 'int_steps' : :obj:`int` - Integration steps to time. - 'adjust_max_skin' : :obj:`bool`, optional - If ``True``, the value of ``max_skin`` is reduced - to the maximum permissible skin (in case the passed - value is too large). Set to ``False`` by default. + min_skin : :obj:`float` + Minimum skin to test. + max_skin : :obj:`float` + Maximum skin. + tol : :obj:`float` + Accuracy in skin to tune to. + int_steps : :obj:`int` + Integration steps to time. + adjust_max_skin : :obj:`bool`, optional + If ``True``, the value of ``max_skin`` is reduced + to the maximum permissible skin (in case the passed + value is too large). Set to ``False`` by default. Returns ------- - :attr:`skin` + :obj:`float` : + The :attr:`skin` """ c_tune_skin(min_skin, max_skin, tol, int_steps, adjust_max_skin) diff --git a/src/python/espressomd/cluster_analysis.py b/src/python/espressomd/cluster_analysis.py index eaaa28e1c14..d9788dba118 100644 --- a/src/python/espressomd/cluster_analysis.py +++ b/src/python/espressomd/cluster_analysis.py @@ -65,7 +65,7 @@ class ClusterStructure(ScriptInterfaceHelper): Attributes ---------- - pair_criterion: Instance of PairCriterion or derived classes + pair_criterion: classes derived from ``_PairCriterion`` Criterion to decide whether two particles are neighbors. clusters: behaves like a read-only dictionary @@ -107,7 +107,8 @@ def clear(self): return self.call_method("clear") def cluster_ids(self): - """returns a list of all cluster ids of the clusters in the structure + """ + Returns a list of all cluster ids of the clusters in the structure. """ return self.call_method("cluster_ids") diff --git a/src/python/espressomd/collision_detection.pyx b/src/python/espressomd/collision_detection.pyx index e4d1cee5005..2f3aa6968f6 100644 --- a/src/python/espressomd/collision_detection.pyx +++ b/src/python/espressomd/collision_detection.pyx @@ -40,7 +40,7 @@ class CollisionDetection(ScriptInterfaceHelper): def validate(self): """Validates the parameters of the collision detection. - This is called automatically on parameter change + This is called automatically on parameter change """ return self.call_method("validate") @@ -60,39 +60,42 @@ class CollisionDetection(ScriptInterfaceHelper): Parameters ---------- - mode : One of "off", "bind_centers", "bind_at_point_of_collision", "bind_three_particles", "glue_to_surface" - Collision detection mode + mode : str, \{"off", "bind_centers", "bind_at_point_of_collision", "bind_three_particles", "glue_to_surface"\} + Collision detection mode distance : :obj:`float` - Distance below which a pair of particles is considered in the collision detection + Distance below which a pair of particles is considered in the + collision detection - bond_centers : Instance of :class:`espressomd.interactions.BondedInteraction` - Bond to add between the colliding particles + bond_centers : :obj:`espressomd.interactions.BondedInteraction` + Bond to add between the colliding particles - bond_vs : Instance of :class:`espressomd.interactions.BondedInteraction` - Bond to add between virtual sites (for modes using virtual sites) + bond_vs : :obj:`espressomd.interactions.BondedInteraction` + Bond to add between virtual sites (for modes using virtual sites) part_type_vs : :obj:`int` - Particle type of the virtual sites being created on collision (virtual sites based modes) + Particle type of the virtual sites being created on collision + (virtual sites based modes) part_type_to_be_glued : :obj:`int` - particle type for "glue_to_surface" mode. See user guide. + particle type for ``"glue_to_surface"`` mode. See user guide. part_type_to_attach_vs_to : :obj:`int` - particle type for "glue_to_surface" mode. See user guide. + particle type for ``"glue_to_surface"`` mode. See user guide. part_type_after_glueing : :obj:`int` - particle type for "glue_to_surface" mode. See user guide. + particle type for ``"glue_to_surface"`` mode. See user guide. distance_glued_particle_to_vs : :obj:`float` - Distance for "glue_to_surface" mode. See user guide. + Distance for ``"glue_to_surface"`` mode. See user guide. - bond_three_particles : Instance of :class:`espressomd.interactions.BondedInteraction` - First angular bond for the "bind_three_particles" mode. See user guide + bond_three_particles : :obj:`espressomd.interactions.BondedInteraction` + First angular bond for the ``"bind_three_particles"`` mode. See + user guide three_particle_binding_angle_resolution : :obj:`int` - Resolution for the angular bonds (mode "bind_three_particles"). - Resolution+1 bonds are needed to accommodate the case of a 180 degrees + Resolution for the angular bonds (mode ``"bind_three_particles"``). + Resolution+1 bonds are needed to accommodate the case of a 180 degrees """ @@ -102,8 +105,9 @@ class CollisionDetection(ScriptInterfaceHelper): # Completeness of parameter set if not (set(kwargs.keys()) == set(self._params_for_mode(kwargs["mode"]))): - raise Exception("Parameter set does not match mode. ", kwargs[ - "mode"], "requires ", self._params_for_mode(kwargs["mode"])) + raise Exception("Parameter set does not match mode. ", + kwargs["mode"], "requires ", + self._params_for_mode(kwargs["mode"])) # Mode kwargs["mode"] = self._int_mode[kwargs["mode"]] @@ -135,12 +139,13 @@ class CollisionDetection(ScriptInterfaceHelper): return {k: res[k] for k in self._params_for_mode(res["mode"])} def _convert_param(self, name, value): - """Handles type conversion core -> python + """ + Handles type conversion core -> python - Bond types: int -> BondedInteraction - mode: int -> string + Bond types: int -> BondedInteraction + mode: int -> string - """ + """ # Py3: Cast from binary to normal string. Don't understand, why a # binary string can even occur, here, but it does. name = to_str(name) @@ -189,7 +194,7 @@ class CollisionDetection(ScriptInterfaceHelper): return key raise Exception("Unknown integer collision mode %d" % int_mode) -# Pickle support + # Pickle support def __reduce__(self): return _restore_collision_detection, (self.get_params(),) diff --git a/src/python/espressomd/comfixed.py b/src/python/espressomd/comfixed.py index 88f137cc422..20996370fa2 100644 --- a/src/python/espressomd/comfixed.py +++ b/src/python/espressomd/comfixed.py @@ -31,8 +31,7 @@ class ComFixed(ScriptInterfaceHelper): Parameters ---------- types : array_like - List of types for which the center of mass - should be fixed. + List of types for which the center of mass should be fixed. """ _so_name = "ComFixed" diff --git a/src/python/espressomd/constraints.py b/src/python/espressomd/constraints.py index f2b873088e6..3fb17af5888 100644 --- a/src/python/espressomd/constraints.py +++ b/src/python/espressomd/constraints.py @@ -67,7 +67,7 @@ def remove(self, constraint): Parameters ---------- - constraint : Instance of :class:`espressomd.constraints.Constraint` + constraint : :obj:`espressomd.constraints.Constraint` """ @@ -100,17 +100,16 @@ class ShapeBasedConstraint(Constraint): Attributes ---------- only_positive : :obj:`bool` - Act only in the direction of positive normal, - only useful if penetrable is ``True``. + Act only in the direction of positive normal, + only useful if penetrable is ``True``. particle_type : int - Interaction type of the constraint. + Interaction type of the constraint. particle_velocity : array of :obj:`float` - Interaction velocity of the boundary + Interaction velocity of the boundary penetrable : :obj:`bool` - Whether particles are allowed to penetrate the - constraint. + Whether particles are allowed to penetrate the constraint. shape : :class:`espressomd.shapes.Shape` - One of the shapes from :mod:`espressomd.shapes` + One of the shapes from :mod:`espressomd.shapes` See Also ---------- @@ -130,7 +129,6 @@ class ShapeBasedConstraint(Constraint): >>> >>> # place a trapped particle inside this sphere >>> system.part.add(id=0, pos=[5, 5, 5], type=1) - >>> """ @@ -165,10 +163,9 @@ def total_force(self): ... epsilon=1, sigma=1, ... cutoff=2**(1. / 6), shift="auto") >>> - >>> >>> floor = system.constraints.add(shape=shapes.Wall(normal=[0, 0, 1], dist=0.0), ... particle_type=0, penetrable=False, only_positive=False) - + >>> >>> system.part.add(id=0, pos=[0,0,1.5], type=0, ext_force=[0, 0, -.1]) >>> # print the particle position as it falls >>> # and print the force it applies on the floor @@ -222,11 +219,11 @@ class that can calculate the required grid dimensions and the coordinates. Attributes ---------- - field_data: array_like :obj:`float`: + field_data: array_like :obj:`float` The actual field please be aware that depending on the interpolation order additional points are used on the boundaries. - grid_spacing: array_like :obj:`float`: + grid_spacing: array_like :obj:`float` The spacing of the grid points. """ @@ -239,8 +236,10 @@ def __init__(self, field, **kwargs): @classmethod def required_dims(cls, box_size, grid_spacing): - """Calculate the grid size and origin needed for specified box size and grid spacing. - Returns the shape and origin (coordinates of [0][0][0]) needed. + """ + Calculate the grid size and origin needed for specified box size and + grid spacing. Returns the shape and origin (coordinates of [0][0][0]) + needed. Arguments --------- @@ -290,8 +289,7 @@ def field_from_fn(cls, box_size, grid_spacing, f, codim=None): @classmethod def field_coordinates(cls, box_size, grid_spacing): - """Returns an array of the coordinates of the grid - points required. + """Returns an array of the coordinates of the grid points required. Arguments --------- @@ -321,14 +319,12 @@ def field(self): class ForceField(_Interpolated): """ - A generic tabulated force field that applies a per particle - scaling factor. + A generic tabulated force field that applies a per-particle scaling factor. Attributes ---------- default_scale : :obj:`float` - Scaling factor for particles that have no - individual scaling factor. + Scaling factor for particles that have no individual scaling factor. particle_scales: array_like (:obj:`int`, :obj:`float`) A list of tuples of ids and scaling factors. For particles in the list the interaction is scaled with @@ -376,7 +372,8 @@ class Gravity(Constraint): """ Gravity force - F = m * g + + :math:`F = m \\cdot g` Attributes ---------- @@ -401,15 +398,15 @@ class LinearElectricPotential(Constraint): """ Electric potential of the form - phi = -E * x + phi0, + :math:`\\phi = -E \\cdot x + \\phi_0`, resulting in the electric field E everywhere. (E.g. in a plate capacitor). The resulting force on the particles are then - F = q * E + :math:`F = q \\cdot E` - where q is the charge of the particle. + where :math:`q` is the charge of the particle. Attributes ---------- @@ -417,7 +414,7 @@ class LinearElectricPotential(Constraint): The electric field. phi0 : :obj:`float` - The potential at the origin + The potential at the origin """ @@ -441,13 +438,13 @@ class ElectricPlaneWave(Constraint): """ Electric field of the form - E = E0 * sin(k * x + omega * t + phi) + :math:`E = E0 \\cdot \\sin(k \\cdot x + \\omega \\cdot t + \\phi)` The resulting force on the particles are then - F = q * E + :math:`F = q \\cdot E` - where q is the charge of the particle. + where :math:`q` is the charge of the particle. This can be used to generate a homogeneous AC field by setting k to zero. @@ -460,7 +457,7 @@ class ElectricPlaneWave(Constraint): omega : :obj:`float` Frequency of the wave phi : :obj:`float` - Optional phase shift, defaults to 0. + Optional phase shift, defaults to 0. """ @@ -494,9 +491,9 @@ class FlowField(_Interpolated): Viscous coupling to a flow field that is interpolated from tabulated data like - F = -gamma * (u(r) - v) + :math:`F = -\\gamma \\cdot \\left( u(r) - v \\right)` - where v is the velocity of the particle. + where :math:`v` is the velocity of the particle. """ @@ -514,9 +511,9 @@ class HomogeneousFlowField(Constraint): Viscous coupling to a flow field that is constant in space with the force - F = -gamma * (u - v) + :math:`F = -\\gamma \\cdot (u - v)` - where v is the velocity of the particle. + where :math:`v` is the velocity of the particle. Attributes ---------- @@ -546,9 +543,9 @@ class ElectricPotential(_Interpolated): calculated numerically from the potential, and the resulting force on the particles are - F = q * E + :math:`F = q \\cdot E` - where q is the charge of the particle. + where :math:`q` is the charge of the particle. """ diff --git a/src/python/espressomd/electrokinetics.pyx b/src/python/espressomd/electrokinetics.pyx index e5e70fc0b62..be87145e485 100644 --- a/src/python/espressomd/electrokinetics.pyx +++ b/src/python/espressomd/electrokinetics.pyx @@ -143,11 +143,11 @@ IF ELECTROKINETICS: Parameters ---------- species : :obj:`int` - species for which the density will apply. + species for which the density will apply. density : :obj:`float` - The value to which the density will be set to. + The value to which the density will be set to. node : numpy-array of type :obj:`int` of length (3) - If set the density will be only applied on this specific node. + If set the density will be only applied on this specific node. """ @@ -177,16 +177,16 @@ IF ELECTROKINETICS: Sets the global density of a species to a specific value for which the whole system will have no net charge. + .. note :: The previous density of the species will be ignored and + it will be homogeneous distributed over the whole system + The species must be charged to begin with. If the + neutralization would lead to a negative species density + an exception will be raised. + Parameters ---------- species : :obj:`int` - The species which will be changed to neutralize the system. - - note : The previous density of the species will be ignored and - it will be homogeneous distributed over the whole system - The species must be charged to begin with. - If the neutralization would lead to a negative species density - an exception will be raised. + The species which will be changed to neutralize the system. """ err = ek_neutralize_system(species.id) @@ -225,7 +225,7 @@ IF ELECTROKINETICS: Parameters ---------- species : :obj:`int` - Species to be initialized. + Species to be initialized. """ self._params["species"].append(species) @@ -245,7 +245,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the boundary is written to. + The path and vtk-file name the boundary is written to. """ lb_lbfluid_print_vtk_boundary(utils.to_char_pointer(path)) @@ -257,7 +257,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the velocity is written to. + The path and vtk-file name the velocity is written to. """ ek_lb_print_vtk_velocity(utils.to_char_pointer(path)) @@ -269,7 +269,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the LB density is written to. + The path and vtk-file name the LB density is written to. """ ek_lb_print_vtk_density(utils.to_char_pointer(path)) @@ -281,7 +281,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the electrostatic potential is written to. + The path and vtk-file name the electrostatic potential is written to. """ ek_print_vtk_potential(utils.to_char_pointer(path)) @@ -293,7 +293,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the LB force is written to. + The path and vtk-file name the LB force is written to. """ ek_print_vtk_lbforce_density(utils.to_char_pointer(path)) @@ -302,12 +302,12 @@ IF ELECTROKINETICS: """ Writes the electrostatic particle potential into a vtk-file. + .. note :: This only works if 'es_coupling' is active. + Parameters ---------- path : :obj:`str` - The path and vtk-file name the electrostatic potential is written to. - - note : This only works if 'es_coupling' is active. + The path and vtk-file name the electrostatic potential is written to. """ @@ -489,7 +489,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the species density is written to. + The path and vtk-file name the species density is written to. """ ek_print_vtk_density(self.id, utils.to_char_pointer(path)) @@ -501,7 +501,7 @@ IF ELECTROKINETICS: Parameters ---------- path : :obj:`str` - The path and vtk-file name the species flux is written to. + The path and vtk-file name the species flux is written to. """ ek_print_vtk_flux(self.id, utils.to_char_pointer(path)) diff --git a/src/python/espressomd/electrostatic_extensions.pyx b/src/python/espressomd/electrostatic_extensions.pyx index 33c3f3fe6f2..afb1558317f 100644 --- a/src/python/espressomd/electrostatic_extensions.pyx +++ b/src/python/espressomd/electrostatic_extensions.pyx @@ -36,51 +36,51 @@ IF ELECTROSTATICS and P3M: Parameters ---------- - gap_size : float, required - The gap size gives the height of the empty region between the system box - and the neighboring artificial images. |es| does not - make sure that the gap is actually empty, this is the users - responsibility. The method will compute fine if the condition is not - fulfilled, however, the error bound will not be reached. Therefore you - should really make sure that the gap region is empty (e.g. with wall - constraints). - maxPWerror : float, required - The maximal pairwise error sets the least upper bound (LUB) error of - the force between any two charges without prefactors (see the papers). - The algorithm tries to find parameters to meet this LUB requirements or - will throw an error if there are none. - delta_mid_top : float, optional - This parameter sets the dielectric contrast - between the upper boundary and the simulation - box :math:`\\Delta_t`. - delta_mid_bottom : float, optional - This parameter sets the dielectric contrast - between the lower boundary and the simulation - box :math:`\\Delta_b`. - const_pot : bool, optional - Selector parameter for setting a constant - electric potential between the top and bottom - of the simulation box. - pot_diff : float, optional - If const_pot mode is selected this parameter - controls the applied voltage. - neutralize : int, optional - By default, ELC just as P3M adds a homogeneous neutralizing background - to the system in case of a net charge. However, unlike in three dimensions, - this background adds a parabolic potential across the - slab :cite:`ballenegger09a`. Therefore, under normal circumstance, you will - probably want to disable the neutralization for non-neutral systems. - This corresponds then to a formal regularization of the forces and - energies :cite:`ballenegger09a`. Also, if you add neutralizing walls - explicitly as constraints, you have to disable the neutralization. - When using a dielectric contrast or full metallic walls (`delta_mid_top - != 0` or `delta_mid_bot != 0` or `const_pot=True`), `neutralize` is - overwritten and switched off internally. Note that the special case of - non-neutral systems with a *non-metallic* dielectric jump (eg. - `delta_mid_top` or `delta_mid_bot` in `]-1,1[`) is not covered by the - algorithm and will throw an error. - far_cut : float, optional - Cut off radius, use with care, intended for testing purposes. + gap_size : :obj:`float`, required + The gap size gives the height of the empty region between the system box + and the neighboring artificial images. |es| does not + make sure that the gap is actually empty, this is the users + responsibility. The method will compute fine if the condition is not + fulfilled, however, the error bound will not be reached. Therefore you + should really make sure that the gap region is empty (e.g. with wall + constraints). + maxPWerror : :obj:`float`, required + The maximal pairwise error sets the least upper bound (LUB) error of + the force between any two charges without prefactors (see the papers). + The algorithm tries to find parameters to meet this LUB requirements or + will throw an error if there are none. + delta_mid_top : :obj:`float`, optional + This parameter sets the dielectric contrast + between the upper boundary and the simulation + box :math:`\\Delta_t`. + delta_mid_bottom : :obj:`float`, optional + This parameter sets the dielectric contrast + between the lower boundary and the simulation + box :math:`\\Delta_b`. + const_pot : :obj:`bool`, optional + Selector parameter for setting a constant + electric potential between the top and bottom + of the simulation box. + pot_diff : :obj:`float`, optional + If ``const_pot mode`` is enabled this parameter + controls the applied voltage. + neutralize : :obj:`int`, optional + By default, ELC just as P3M adds a homogeneous neutralizing background + to the system in case of a net charge. However, unlike in three dimensions, + this background adds a parabolic potential across the + slab :cite:`ballenegger09a`. Therefore, under normal circumstance, you will + probably want to disable the neutralization for non-neutral systems. + This corresponds then to a formal regularization of the forces and + energies :cite:`ballenegger09a`. Also, if you add neutralizing walls + explicitly as constraints, you have to disable the neutralization. + When using a dielectric contrast or full metallic walls (`delta_mid_top + != 0` or `delta_mid_bot != 0` or `const_pot=True`), `neutralize` is + overwritten and switched off internally. Note that the special case of + non-neutral systems with a *non-metallic* dielectric jump (eg. + `delta_mid_top` or `delta_mid_bot` in `]-1,1[`) is not covered by the + algorithm and will throw an error. + far_cut : :obj:`float`, optional + Cut off radius, use with care, intended for testing purposes. """ def validate_params(self): diff --git a/src/python/espressomd/electrostatics.pyx b/src/python/espressomd/electrostatics.pyx index b4f46024504..bc28cdc10ae 100644 --- a/src/python/espressomd/electrostatics.pyx +++ b/src/python/espressomd/electrostatics.pyx @@ -55,13 +55,13 @@ IF ELECTROSTATICS == 1: cdef class ElectrostaticInteraction(actors.Actor): def _tune(self): raise Exception( - "Subclasses of ElectrostaticInteraction must define the _tune() \ - method or chosen method does not support tuning.") + "Subclasses of ElectrostaticInteraction must define the _tune()" + "method or chosen method does not support tuning.") def _set_params_in_es_core(self): raise Exception( - "Subclasses of ElectrostaticInteraction must define the \ - _set_params_in_es_core() method.") + "Subclasses of ElectrostaticInteraction must define the" + "_set_params_in_es_core() method.") def _deactivate_method(self): deactivate_method() diff --git a/src/python/espressomd/interactions.pxd b/src/python/espressomd/interactions.pxd index 495105b2cec..1ea82c994be 100644 --- a/src/python/espressomd/interactions.pxd +++ b/src/python/espressomd/interactions.pxd @@ -16,6 +16,7 @@ # You should have received a copy of the GNU General Public License # along with this program. If not, see . # + # Handling of interactions from libcpp.string cimport string @@ -315,15 +316,14 @@ cdef extern from "bonded_interactions/bonded_interaction_data.hpp": double drmax2 double drmax2i - -#* Parameters for oif_global_forces */ + #* Parameters for oif_global_forces */ cdef struct Oif_global_forces_bond_parameters: double A0_g double ka_g double V0 double kv -#* Parameters for oif_local_forces */ + #* Parameters for oif_local_forces */ cdef struct Oif_local_forces_bond_parameters: double r0 double ks @@ -335,14 +335,13 @@ cdef extern from "bonded_interactions/bonded_interaction_data.hpp": double kal double kvisc -#* Parameters for harmonic bond Potential */ + #* Parameters for harmonic bond Potential */ cdef struct Harmonic_bond_parameters: double k double r double r_cut - -#* Parameters for thermalized bond */ + #* Parameters for thermalized bond */ cdef struct Thermalized_bond_parameters: double temp_com double gamma_com @@ -350,46 +349,42 @@ cdef extern from "bonded_interactions/bonded_interaction_data.hpp": double gamma_distance double r_cut -#* Parameters for Bonded Coulomb */ + #* Parameters for Bonded Coulomb */ cdef struct Bonded_coulomb_bond_parameters: double prefactor - -#* Parameters for three body angular potential (bond-angle potentials). + #* Parameters for three body angular potential (bond-angle potentials). cdef struct Angle_bond_parameters: double bend double phi0 double cos_phi0 double sin_phi0 -#* Parameters for three body angular potential (bond_angle_harmonic). + #* Parameters for three body angular potential (bond_angle_harmonic). cdef struct Angle_harmonic_bond_parameters: double bend double phi0 - -#* Parameters for three body angular potential (bond_angle_cosine). + #* Parameters for three body angular potential (bond_angle_cosine). cdef struct Angle_cosine_bond_parameters: double bend double phi0 double cos_phi0 double sin_phi0 - -#* Parameters for three body angular potential (bond_angle_cossquare). + #* Parameters for three body angular potential (bond_angle_cossquare). cdef struct Angle_cossquare_bond_parameters: double bend double phi0 double cos_phi0 -#* Parameters for four body angular potential (dihedral-angle potentials). */ + #* Parameters for four body angular potential (dihedral-angle potentials). */ cdef struct Dihedral_bond_parameters: double mult double bend double phase - -#* Parameters for n-body overlapped potential (n=2,3,4). */ + #* Parameters for n-body overlapped potential (n=2,3,4). */ cdef struct Overlap_bond_parameters: char * filename int type @@ -399,19 +394,19 @@ cdef extern from "bonded_interactions/bonded_interaction_data.hpp": double * para_b double * para_c -#* Parameters for one-directional harmonic potential */ + #* Parameters for one-directional harmonic potential */ cdef struct Umbrella_bond_parameters: double k int dir double r -#* Dummy parameters for -LJ Potential */ + #* Parameters for subt-LJ potential */ cdef struct Subt_lj_bond_parameters: double k double r double r2 -#*Parameters for the rigid_bond/SHAKE/RATTLE ALGORITHM*/ + #* Parameters for the rigid_bond/SHAKE/RATTLE ALGORITHM */ cdef struct Rigid_bond_parameters: #*Length of rigid bond/Constrained Bond*/ # double d @@ -422,7 +417,7 @@ cdef extern from "bonded_interactions/bonded_interaction_data.hpp": #*Velocity Tolerance/Accuracy for termination of RATTLE/SHAKE iterations during velocity corrections */ double v_tol -#* Parameters for IBM Triel */ + #* Parameters for IBM Triel */ cdef cppclass tElasticLaw: pass @@ -441,24 +436,24 @@ cdef extern from "bonded_interactions/bonded_interaction_data.hpp": double k1 double k2 -#* Parameters for IBM Tribend */ + #* Parameters for IBM Tribend */ cdef struct IBM_Tribend_Parameters: double kb double theta0 -#* Parameters for IBM VolCons */ + #* Parameters for IBM VolCons */ cdef struct IBM_VolCons_Parameters: int softID double kappaV double volRef -#* Parameters for Quartic */ + #* Parameters for Quartic */ cdef struct Quartic_bond_parameters: double k0, k1 double r double r_cut -#* Union in which to store the parameters of an individual bonded interaction */ + #* Union in which to store the parameters of an individual bonded interaction */ cdef union Bond_parameters: Fene_bond_parameters fene Oif_global_forces_bond_parameters oif_global_forces diff --git a/src/python/espressomd/interactions.pyx b/src/python/espressomd/interactions.pyx index 026cfbf7935..4403579866b 100644 --- a/src/python/espressomd/interactions.pyx +++ b/src/python/espressomd/interactions.pyx @@ -260,17 +260,17 @@ IF LENNARD_JONES == 1: ---------- epsilon : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. sigma : :obj:`float` - Determines the interaction length scale. + Determines the interaction length scale. cutoff : :obj:`float` - Cutoff distance of the interaction. + Cutoff distance of the interaction. shift : :obj:`float` or :obj:`str` - Constant shift of the potential. (4*epsilon*shift). + Constant shift of the potential. (4*epsilon*shift). offset : :obj:`float`, optional - Offset distance of the interaction. + Offset distance of the interaction. min : :obj:`float`, optional - Restricts the interaction to a minimal distance. + Restricts the interaction to a minimal distance. """ super().set_params(**kwargs) @@ -362,9 +362,9 @@ IF WCA == 1: ---------- epsilon : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. sigma : :obj:`float` - Determines the interaction length scale. + Determines the interaction length scale. """ super().set_params(**kwargs) @@ -514,29 +514,29 @@ IF LENNARD_JONES_GENERIC == 1: Parameters ---------- epsilon : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. sigma : :obj:`float` - Determines the interaction length scale. + Determines the interaction length scale. cutoff : :obj:`float` - Cutoff distance of the interaction. - shift : :obj:`float`, string - Constant shift of the potential. + Cutoff distance of the interaction. + shift : :obj:`float` + Constant shift of the potential. offset : :obj:`float` - Offset distance of the interaction. + Offset distance of the interaction. e1 : :obj:`int` - Exponent of the repulsion term. + Exponent of the repulsion term. e2 : :obj:`int` - Exponent of the attraction term. + Exponent of the attraction term. b1 : :obj:`float` - Prefactor of the repulsion term. + Prefactor of the repulsion term. b2 : :obj:`float` - Prefactor of the attraction term. + Prefactor of the attraction term. delta : :obj:`float`, optional - LJGEN_SOFTCORE parameter. Allows control over how smoothly - the potential drops to zero as lambda approaches zero. + ``LJGEN_SOFTCORE`` parameter delta. Allows control over how + smoothly the potential drops to zero as lambda approaches zero. lam : :obj:`float`, optional - LJGEN_SOFTCORE parameter lambda. Tune the strength of the - interaction. + ``LJGEN_SOFTCORE`` parameter lambda. Tune the strength of the + interaction. """ super().set_params(**kwargs) @@ -581,19 +581,19 @@ IF LJCOS: return(self._params["epsilon"] > 0) def set_params(self, **kwargs): - """ Set parameters for the Lennard-Jones Cosine2 interaction. + """Set parameters for the Lennard-Jones Cosine2 interaction. Parameters ---------- epsilon : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. sigma : :obj:`float` - Determines the interaction length scale. + Determines the interaction length scale. cutoff : :obj:`float` - Cutoff distance of the interaction. + Cutoff distance of the interaction. offset : :obj:`float` - Offset distance of the interaction. + Offset distance of the interaction. """ super().set_params(**kwargs) @@ -667,13 +667,13 @@ IF LJCOS2: ---------- epsilon : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. sigma : :obj:`float` - Determines the interaction length scale. + Determines the interaction length scale. offset : :obj:`float` - Offset distance of the interaction. + Offset distance of the interaction. width : :obj:`float` - Width of interaction. + Width of interaction. """ super().set_params(**kwargs) @@ -739,9 +739,9 @@ IF HAT == 1: Parameters ---------- F_max : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. cutoff : :obj:`float` - Cutoff distance of the interaction. + Cutoff distance of the interaction. """ super().set_params(**kwargs) @@ -804,20 +804,20 @@ IF GAY_BERNE: Parameters ---------- eps : :obj:`float` - Potential well depth. + Potential well depth. sig : :obj:`float` - Interaction range. + Interaction range. cut : :obj:`float` - Cutoff distance of the interaction. + Cutoff distance of the interaction. k1 : :obj:`float` or :obj:`str` - Molecular elongation. + Molecular elongation. k2 : :obj:`float`, optional - Ratio of the potential well depths for the side-by-side - and end-to-end configurations. + Ratio of the potential well depths for the side-by-side + and end-to-end configurations. mu : :obj:`float`, optional - Adjustable exponent. - nu : :obj:`float`, optional - Adjustable exponent. + Adjustable exponent. + nu : :obj:`float`, optional + Adjustable exponent. """ super().set_params(**kwargs) @@ -1017,11 +1017,11 @@ IF SMOOTH_STEP == 1: n : :obj:`int` Exponent of short range repulsion. eps : :obj:`float` - The magnitude of the second (soft) repulsion. + The magnitude of the second (soft) repulsion. k0 : :obj:`float` - Exponential factor in second (soft) repulsion. + Exponential factor in second (soft) repulsion. sig : :obj:`float` - Length scale of second (soft) repulsion. + Length scale of second (soft) repulsion. cutoff : :obj:`float` Cutoff distance of the interaction. @@ -1410,9 +1410,9 @@ IF SOFT_SPHERE == 1: n : :obj:`float` Exponent of the power law. cutoff : :obj:`float` - Cutoff distance of the interaction. + Cutoff distance of the interaction. offset : :obj:`float`, optional - Offset distance of the interaction. + Offset distance of the interaction. """ super().set_params(**kwargs) @@ -1604,9 +1604,9 @@ IF HERTZIAN == 1: Parameters ---------- eps : :obj:`float` - The magnitude of the interaction. + The magnitude of the interaction. sig : :obj:`float` - Parameter sigma which determines the length over which the potential decays. + Parameter sigma which determines the length over which the potential decays. """ super().set_params(**kwargs) @@ -1688,11 +1688,11 @@ IF GAUSSIAN == 1: Parameters ---------- eps : :obj:`float` - Overlap energy epsilon. + Overlap energy epsilon. sig : :obj:`float` - Variance sigma of the Gaussian interaction. + Variance sigma of the Gaussian interaction. cutoff : :obj:`float` - Cutoff distance of the interaction. + Cutoff distance of the interaction. """ super().set_params(**kwargs) @@ -2040,10 +2040,9 @@ class FeneBond(BondedInteraction): k : :obj:`float` Specifies the magnitude of the bond interaction. d_r_max : :obj:`float` - Specifies the maximum stretch and compression length of the - bond. + Specifies the maximum stretch and compression length of the bond. r_0 : :obj:`float`, optional - Specifies the equilibrium length of the bond. + Specifies the equilibrium length of the bond. """ @@ -2102,10 +2101,9 @@ class HarmonicBond(BondedInteraction): k : :obj:`float` Specifies the magnitude of the bond interaction. r_0 : :obj:`float` - Specifies the equilibrium length of the bond. + Specifies the equilibrium length of the bond. r_cut : :obj:`float`, optional - Specifies maximum distance beyond which the bond is considered - broken. + Specifies maximum distance beyond which the bond is considered broken. """ @@ -2159,7 +2157,7 @@ if ELECTROSTATICS: ---------- prefactor : :obj:`float` - Sets the Coulomb prefactor of the bonded Coulomb interaction. + Sets the Coulomb prefactor of the bonded Coulomb interaction. """ def __init__(self, *args, **kwargs): @@ -2200,9 +2198,9 @@ if ELECTROSTATICS: ---------- q1q2 : :obj:`float` - Sets the charge factor of the involved particle pair. Note the - particle charges are used to allow e.g. only partial subtraction - of the involved charges. + Sets the charge factor of the involved particle pair. Note the + particle charges are used to allow e.g. only partial subtraction + of the involved charges. """ def __init__(self, *args, **kwargs): @@ -2317,16 +2315,16 @@ IF THOLE: Parameters ---------- scaling_coeff : :obj:`float` - The factor used in the Thole damping function between - polarizable particles i and j. Usually calculated by - the polarizabilities alpha_i, alpha_j and damping - parameters a_i, a_j via - scaling_coeff = (a_i+a_j)/2 / ((alpha_i*alpha_j)^(1/2))^(1/3) + The factor used in the Thole damping function between + polarizable particles i and j. Usually calculated by + the polarizabilities alpha_i, alpha_j and damping + parameters a_i, a_j via + scaling_coeff = (a_i+a_j)/2 / ((alpha_i*alpha_j)^(1/2))^(1/3) q1q2: :obj:`float` - charge factor of the involved charges. Has to be set because - it acts only on the portion of the Drude core charge that is - associated to the dipole of the atom. For charged, polarizable - atoms that charge is not equal to the particle charge property. + charge factor of the involved charges. Has to be set because + it acts only on the portion of the Drude core charge that is + associated to the dipole of the atom. For charged, polarizable + atoms that charge is not equal to the particle charge property. """ super().set_params(**kwargs) @@ -2576,15 +2574,14 @@ class Tabulated(BondedInteraction): Parameters ---------- - type : :obj:`str` - The type of bond, one of 'distance', 'angle' or - 'dihedral'. + type : :obj:`str`, \{'distance', 'angle' or 'dihedral'\} + The type of bond. min : :obj:`float` The minimal interaction distance. Has to be 0 if - type is 'angle' or 'dihedral' + ``type`` is ``'angle'`` or ``'dihedral'`` max : :obj:`float` The maximal interaction distance. Has to be pi if - type is 'angle' or 2pi if 'dihedral' + ``type`` is ``'angle'`` or 2pi if ``'dihedral'`` energy: array_like :obj:`float` The energy table. force: array_like :obj:`float` @@ -2733,13 +2730,13 @@ IF TABULATED == 1: ---------- min : :obj:`float`, - The minimal interaction distance. + The minimal interaction distance. max : :obj:`float`, - The maximal interaction distance. + The maximal interaction distance. energy: array_like :obj:`float` - The energy table. + The energy table. force: array_like :obj:`float` - The force table. + The force table. """ super().set_params(**kwargs) @@ -3067,8 +3064,8 @@ class IBM_Tribend(BondedInteraction): initializing reference state kb : :obj:`float` Specifies bending modulus - refShape : :obj:`str` - Flat or Initial + refShape : :obj:`str`, \{'Flat', 'Initial'\} + Reference shape """ @@ -3100,8 +3097,9 @@ class IBM_Tribend(BondedInteraction): flat = True if self._params["refShape"] == "Initial": flat = False - IBM_Tribend_SetParams(self._bond_id, self._params["ind1"], self._params[ - "ind2"], self._params["ind3"], self._params["ind4"], self._params["kb"], flat) + IBM_Tribend_SetParams(self._bond_id, self._params["ind1"], + self._params["ind2"], self._params["ind3"], + self._params["ind4"], self._params["kb"], flat) # IBM VolCons @@ -3243,7 +3241,10 @@ class OifLocalForces(BondedInteraction): def _set_params_in_es_core(self): oif_local_forces_set_params( - self._bond_id, self._params["r0"], self._params["ks"], self._params["kslin"], self._params["phi0"], self._params["kb"], self._params["A01"], self._params["A02"], self._params["kal"], self._params["kvisc"]) + self._bond_id, self._params["r0"], self._params["ks"], + self._params["kslin"], self._params["phi0"], self._params["kb"], + self._params["A01"], self._params["A02"], self._params["kal"], + self._params["kvisc"]) IF MEMBRANE_COLLISION == 1: class OifOutDirection(BondedInteraction): @@ -3320,9 +3321,6 @@ class QuarticBond(BondedInteraction): def set_default_params(self): """Sets parameters that are not required to their default value. - """ - """Sets parameters that are not required to their default value. - """ self._params = {"k0": 0., "k1": 0., @@ -3370,11 +3368,13 @@ IF ELECTROSTATICS: class BondedInteractions: - """Represents the bonded interactions. + """ + Represents the bonded interactions. - Individual interactions can be accessed using - BondedInteractions[i], where i is the bond id. Will return a bonded interaction - from bonded_interaction_classes""" + Individual interactions can be accessed using ``BondedInteractions[i]``, + where ``i`` is the bond id. Will return a bonded interaction + from ``bonded_interaction_classes`` + """ def __getitem__(self, key): if not is_valid_type(key, int): diff --git a/src/python/espressomd/lb.pyx b/src/python/espressomd/lb.pyx index 769b04fff05..b84d92853d2 100644 --- a/src/python/espressomd/lb.pyx +++ b/src/python/espressomd/lb.pyx @@ -319,12 +319,12 @@ IF CUDA: Parameters ---------- positions : numpy-array of type :obj:`float` of shape (N,3) - The 3-dimensional positions. + The 3-dimensional positions. Returns ------- velocities : numpy-array of type :obj:`float` of shape (N,3) - The 3-dimensional LB fluid velocities. + The 3-dimensional LB fluid velocities. Raises ------ @@ -332,8 +332,8 @@ IF CUDA: If shape of ``positions`` not (N,3). """ - assert positions.shape[ - 1] == 3, "The input array must have shape (N,3)" + assert positions.shape[1] == 3, \ + "The input array must have shape (N,3)" cdef int length length = positions.shape[0] velocities = np.empty_like(positions) diff --git a/src/python/espressomd/magnetostatic_extensions.pyx b/src/python/espressomd/magnetostatic_extensions.pyx index 752926f925e..9272f692af2 100644 --- a/src/python/espressomd/magnetostatic_extensions.pyx +++ b/src/python/espressomd/magnetostatic_extensions.pyx @@ -42,12 +42,12 @@ IF DIPOLES and DP3M: Attributes ---------- far_cut : :obj:`float` - Cutoff of the exponential sum. + Cutoff of the exponential sum. gap_size : :obj:`float` - Size of the empty gap. Note that DLC relies on the user to make sure that - this condition is fulfilled. + Size of the empty gap. Note that DLC relies on the user to make sure that + this condition is fulfilled. maxPWerror : :obj:`float` - Maximal pairwise error of the potential and force. + Maximal pairwise error of the potential and force. """ diff --git a/src/python/espressomd/magnetostatics.pyx b/src/python/espressomd/magnetostatics.pyx index 263ec13ac5a..c1162c8d351 100644 --- a/src/python/espressomd/magnetostatics.pyx +++ b/src/python/espressomd/magnetostatics.pyx @@ -34,7 +34,7 @@ IF DIPOLES == 1: Attributes ---------- prefactor : :obj:`float` - Magnetostatics prefactor (:math:`\mu_0/(4\pi)`) + Magnetostatics prefactor (:math:`\\mu_0/(4\\pi)`) """ @@ -69,7 +69,7 @@ IF DP3M == 1: Attributes ---------- prefactor : :obj:`float` - Magnetostatics prefactor (:math:`\mu_0/(4\pi)`) + Magnetostatics prefactor (:math:`\\mu_0/(4\\pi)`) accuracy : :obj:`float` P3M tunes its parameters to provide this target accuracy. alpha : :obj:`float` @@ -248,7 +248,7 @@ IF DIPOLES == 1: ---------- prefactor : :obj:`float` - Magnetostatics prefactor (:math:`\mu_0/(4\pi)`) + Magnetostatics prefactor (:math:`\\mu_0/(4\\pi)`) """ @@ -283,7 +283,7 @@ IF DIPOLES == 1: Attributes ---------- prefactor : :obj:`float` - Magnetostatics prefactor (:math:`\mu_0/(4\pi)`) + Magnetostatics prefactor (:math:`\\mu_0/(4\\pi)`) n_replica : :obj:`int` Number of replicas to be taken into account at periodic boundaries. @@ -320,7 +320,7 @@ IF DIPOLES == 1: Attributes ---------- prefactor : :obj:`float` - Magnetostatics prefactor (:math:`\mu_0/(4\pi)`) + Magnetostatics prefactor (:math:`\\mu_0/(4\\pi)`) method_name : :obj:`str` Name of the method as defined in Scafacos method_params : :obj:`dict` @@ -361,7 +361,7 @@ IF DIPOLES == 1: Attributes ---------- prefactor : :obj:`float` - Magnetostatics prefactor (:math:`\mu_0/(4\pi)`) + Magnetostatics prefactor (:math:`\\mu_0/(4\\pi)`) """ diff --git a/src/python/espressomd/minimize_energy.pyx b/src/python/espressomd/minimize_energy.pyx index 57c7472d2c9..daf0f0d47ba 100644 --- a/src/python/espressomd/minimize_energy.pyx +++ b/src/python/espressomd/minimize_energy.pyx @@ -28,13 +28,13 @@ cdef class MinimizeEnergy: Parameters ---------- f_max : :obj:`float` - Maximal allowed force. + Maximal allowed force. gamma : :obj:`float` - Dampening constant. + Dampening constant. max_steps : :obj:`int` - Maximal number of iterations. + Maximal number of iterations. max_displacement : :obj:`float` - Maximal allowed displacement per step. + Maximal allowed displacement per step. """ cdef object _params @@ -51,7 +51,7 @@ cdef class MinimizeEnergy: self._params = self.default_params() return - # Check if all required keys are given + # Check if all required keys are given for k in self.required_keys(): if k not in kwargs: raise ValueError( @@ -99,6 +99,7 @@ cdef class MinimizeEnergy: Perform energy minimization sweep. """ - minimize_energy_init(self._params["f_max"], self._params["gamma"], self._params[ - "max_steps"], self._params["max_displacement"]) + minimize_energy_init(self._params["f_max"], self._params["gamma"], + self._params["max_steps"], + self._params["max_displacement"]) mpi_minimize_energy() diff --git a/src/python/espressomd/pair_criteria.py b/src/python/espressomd/pair_criteria.py index f3b5a355088..8c6664ada9d 100644 --- a/src/python/espressomd/pair_criteria.py +++ b/src/python/espressomd/pair_criteria.py @@ -22,7 +22,11 @@ class _PairCriterion(ScriptInterfaceHelper): def decide(self, p1, p2): """Makes a decision based on the two particles specified. - p1,p2 : Instances of ParticleHandle or integers containing the particle id. + + Parameters + ---------- + p1, p2 : :obj:`ParticleHandle` or :obj:`int` containing the particle id. + Particle pair. """ id1 = None id2 = None @@ -47,7 +51,7 @@ class DistanceCriterion(_PairCriterion): The following parameters can be passed to the constructor, changed via set_params() and retrieved via get_params() - cut_off : float + cut_off : :obj:`float` distance cut off for the criterion """ _so_name = "PairCriteria::DistanceCriterion" @@ -65,7 +69,7 @@ class EnergyCriterion(_PairCriterion): The following parameters can be passed to the constructor, changed via set_params() and retrieved via get_params() - cut_off : float + cut_off : :obj:`float` energy cut off for the criterion """ _so_name = "PairCriteria::EnergyCriterion" @@ -80,7 +84,7 @@ class BondCriterion(_PairCriterion): The following parameters can be passed to the constructor, changed via set_params() and retrieved via get_params() - bond_type : int + bond_type : :obj:`int` numeric type of the bond """ _so_name = "PairCriteria::BondCriterion" diff --git a/src/python/espressomd/particle_data.pyx b/src/python/espressomd/particle_data.pyx index 2062459772a..16264826ac5 100644 --- a/src/python/espressomd/particle_data.pyx +++ b/src/python/espressomd/particle_data.pyx @@ -96,7 +96,7 @@ cdef class ParticleHandle: The particle type for nonbonded interactions. type : :obj:`int` - Nonbonded interactions act between different types of particles. + Nonbonded interactions act between different types of particles. .. note:: The value of `type` has to be an integer >= 0. @@ -119,13 +119,13 @@ cdef class ParticleHandle: The molecule id of the Particle. mol_id : :obj:`int` - The particle mol_id is used to differentiate between - particles belonging to different molecules, e.g. when virtual - sites are used, or object-in-fuid cells. The default - `mol_id` for all particles is 0. + The particle ``mol_id`` is used to differentiate between + particles belonging to different molecules, e.g. when virtual + sites are used, or object-in-fuid cells. The default + ``mol_id`` for all particles is 0. .. note:: - The value of `mol_id` has to be an integer >= 0. + The value of ``mol_id`` has to be an integer >= 0. """ @@ -145,7 +145,7 @@ cdef class ParticleHandle: The unwrapped (not folded into central box) particle position. pos : list of :obj:`float` - A list of three floats representing the particles's absolute position. + A list of three floats representing the particles's absolute position. """ @@ -167,7 +167,7 @@ cdef class ParticleHandle: The wrapped (folded into central box) position vector of a particle. pos : list of :obj:`float` - A list of three floats representing the particles's position. + A list of three floats representing the particles's position. .. note:: Setting the folded position is ambiguous and is thus not possible, please use `pos`. @@ -209,9 +209,8 @@ cdef class ParticleHandle: """ The image box the particles is in. - This is the number of times - the particle position has been folded by the box length in each - direction. + This is the number of times the particle position has been folded by + the box length in each direction. """ def __get__(self): @@ -274,13 +273,13 @@ cdef class ParticleHandle: # Bonds property bonds: """ - The bonds stored by this particle. Note that bonds are only stored by one partner. - You need to define a bonded interaction. + The bonds stored by this particle. Note that bonds are only stored by + one partner. You need to define a bonded interaction. bonds : list/tuple of tuples/lists - a bond tuple is specified as a bond identifier associated with - a particle `(bond_ID, part_ID)`. A single particle may contain - multiple such tuples. + a bond tuple is specified as a bond identifier associated with + a particle `(bond_ID, part_ID)`. A single particle may contain + multiple such tuples. See Also -------- @@ -374,21 +373,21 @@ cdef class ParticleHandle: The particle angular velocity the lab frame. omega_lab : list of :obj:`float` - List of three floats giving the particle angular - velocity as measured from the lab frame. + List of three floats giving the particle angular + velocity as measured from the lab frame. .. note:: - This needs the feature ROTATION. + This needs the feature ``ROTATION``. If you set the angular velocity of the particle in the lab frame, the orientation of the particle - (:attr:`espressomd.particle_data.ParticleHandle.quat`) must be - set before setting omega_lab, otherwise the conversion from + (:attr:`~espressomd.particle_data.ParticleHandle.quat`) must be + set before setting ``omega_lab``, otherwise the conversion from lab to body frame will not be handled properly. See Also --------- - :attr:`espressomd.particle_data.ParticleHandle.omega_body` + :attr:`~espressomd.particle_data.ParticleHandle.omega_body` """ @@ -409,11 +408,11 @@ cdef class ParticleHandle: Particle quaternion representation. quat : list fo :obj:`float` (of length four) - This list of four floats sets the quaternion representation - of the rotational position of this particle. + This list of four floats sets the quaternion representation + of the rotational position of this particle. .. note:: - This needs the feature ROTATION. + This needs the feature ``ROTATION``. """ @@ -432,26 +431,26 @@ cdef class ParticleHandle: pointer_to_quat(self.particle_data, x) return array_locked([x[0], x[1], x[2], x[3]]) -# Director ( z-axis in body fixed frame) + # Director (z-axis in body fixed frame) property director: """ Director. .. note:: Setting the director is not implemented. - This needs the feature ROTATION. + This needs the feature ``ROTATION``. """ def __set__(self, _q): raise AttributeError( - "Setting the director is not implemented in the c++-core of Espresso.") + "Setting the director is not implemented in the C++-core of Espresso.") def __get__(self): self.update_particle_data() return make_array_locked(self.particle_data.r.calc_director()) - # ROTATIONAL_INERTIA + # ROTATIONAL_INERTIA property omega_body: """ The particle angular velocity in body frame. @@ -462,7 +461,7 @@ cdef class ParticleHandle: particles co-rotating frame (or body frame). .. note:: - This needs the feature ROTATION. + This needs the feature ``ROTATION``. """ @@ -491,7 +490,7 @@ cdef class ParticleHandle: .. note:: The orientation of the particle - (:attr:`espressomd.particle_data.ParticleHandle.quat`) must be + (:attr:`~espressomd.particle_data.ParticleHandle.quat`) must be set before setting this property, otherwise the conversion from lab to body frame will not be handled properly. @@ -529,7 +528,7 @@ cdef class ParticleHandle: and the fixed (lab) frame are co-aligned. .. note:: - This needs the feature ROTATIONAL_INERTIA. + This needs the feature ``ROTATIONAL_INERTIA``. """ @@ -593,7 +592,7 @@ cdef class ParticleHandle: q : :obj:`float` .. note:: - This needs the feature ELECTROSTATICS. + This needs the feature ``ELECTROSTATICS``. """ @@ -618,11 +617,11 @@ cdef class ParticleHandle: mu_E : :obj:`float` This effectivly acts as a velocity offset between - an Lattice-Boltzmann fluid and the particle. Has only + a lattice-Boltzmann fluid and the particle. Has only an effect if LB is turned on. .. note:: - This needs the feature LB_ELECTROHYDRODYNAMICS. + This needs the feature ``LB_ELECTROHYDRODYNAMICS``. """ @@ -650,10 +649,10 @@ cdef class ParticleHandle: Declares the particles as virtual (1) or non-virtual (0, default). - virtual : integer + virtual : :obj:`int` .. note:: - This needs the feature VIRTUAL_SITES + This needs the feature ``VIRTUAL_SITES`` """ @@ -673,13 +672,13 @@ cdef class ParticleHandle: property vs_quat: """ Virtual site quaternion. - This quaternion describes the virtual particles orientation in the body - fixed frame of the related real particle. + This quaternion describes the virtual particles orientation in the + body fixed frame of the related real particle. vs_quat : array_like of :obj:`float` .. note:: - This needs the feature VIRTUAL_SITES_RELATIVE. + This needs the feature ``VIRTUAL_SITES_RELATIVE``. """ @@ -710,7 +709,7 @@ cdef class ParticleHandle: vs_relative : tuple: (PID, distance, (q1,q2,q3,q4)) .. note:: - This needs the feature VIRTUAL_SITES_RELATIVE + This needs the feature ``VIRTUAL_SITES_RELATIVE`` """ @@ -759,7 +758,7 @@ cdef class ParticleHandle: dip : list of :obj:`float` .. note:: - This needs the feature DIPOLES. + This needs the feature ``DIPOLES``. """ @@ -784,7 +783,7 @@ cdef class ParticleHandle: dipm : :obj:`float` .. note:: - This needs the feature DIPOLES. + This needs the feature ``DIPOLES``. """ @@ -807,7 +806,7 @@ cdef class ParticleHandle: ext_force : list of :obj:`float` .. note:: - This needs the feature EXTERNAL_FORCES. + This needs the feature ``EXTERNAL_FORCES``. """ @@ -846,7 +845,7 @@ cdef class ParticleHandle: will fix motion for particle with index ``INDEX`` only in z. .. note:: - This needs the feature EXTERNAL_FORCES. + This needs the feature ``EXTERNAL_FORCES``. """ @@ -878,7 +877,7 @@ cdef class ParticleHandle: .. note:: * This torque is specified in the laboratory frame! - * This needs the feature EXTERNAL_FORCES and ROTATION. + * This needs features ``EXTERNAL_FORCES`` and ``ROTATION``. """ @@ -911,7 +910,8 @@ cdef class ParticleHandle: gamma : list of :obj:`float` .. note:: - This needs the feature LANGEVIN_PER_PARTICLE and PARTICLE_ANISOTROPY. + This needs features ``LANGEVIN_PER_PARTICLE`` and + ``PARTICLE_ANISOTROPY``. See Also ---------- @@ -947,7 +947,7 @@ cdef class ParticleHandle: gamma : :obj:`float` .. note:: - This needs the feature LANGEVIN_PER_PARTICLE. + This needs the feature ``LANGEVIN_PER_PARTICLE``. See Also ---------- @@ -974,7 +974,8 @@ cdef class ParticleHandle: gamma_rot : list of :obj:`float` .. note:: - This needs the feature LANGEVIN_PER_PARTICLE, ROTATION and PARTICLE_ANISOTROPY. + This needs features ``LANGEVIN_PER_PARTICLE``, + ``ROTATION`` and ``PARTICLE_ANISOTROPY``. """ def __set__(self, _gamma_rot): @@ -1023,7 +1024,7 @@ cdef class ParticleHandle: temp: :obj:`float` .. note:: - This needs the feature LANGEVIN_PER_PARTICLE. + This needs the feature ``LANGEVIN_PER_PARTICLE``. """ @@ -1041,16 +1042,17 @@ cdef class ParticleHandle: IF ROTATION: property rotation: """ - Switches the particle's rotational degrees of freedom in the Cartesian axes in the body-fixed frame - The content of the torque and omega variables are meaningless, for the co-ordinates for which + Switches the particle's rotational degrees of freedom in the + Cartesian axes in the body-fixed frame. The content of the torque + and omega variables are meaningless for the co-ordinates for which rotation is disabled. The default is not to integrate any rotational degrees of freedom. - rotation : (int,int,int) + rotation : list of :obj:`int` .. note:: - This needs the feature ROTATION. + This needs the feature ``ROTATION``. """ @@ -1088,7 +1090,7 @@ cdef class ParticleHandle: The exclusion list of particles where nonbonded interactions are ignored. .. note:: - This needs the feature EXCLUSIONS. + This needs the feature ``EXCLUSIONS``. """ @@ -1123,7 +1125,8 @@ cdef class ParticleHandle: Parameters ----------- - _partner : partner + _partner : :obj:`int` + partner """ if _partner in self.exclusions: @@ -1158,55 +1161,53 @@ cdef class ParticleHandle: entries depending whether there is an implicit fluid (i.e. with the Langevin thermostat) of an explicit fluid (with LB). - Swimming enables the particle to be self-propelled in the direction determined by its - quaternion. For setting the quaternion of the particle see . The + Swimming enables the particle to be self-propelled in the direction + determined by its quaternion. For setting the quaternion of the + particle see :attr:`~espressomd.particle_data.ParticleHandle.quat`. The self-propulsion speed will relax to a constant velocity, that is specified by - `v_swim` . Alternatively it is possible to achieve a constant velocity by - imposing a constant force term `f_swim` that is balanced by friction of a + ``v_swim``. Alternatively it is possible to achieve a constant velocity by + imposing a constant force term ``f_swim`` that is balanced by friction of a (Langevin) thermostat. The way the velocity of the particle decays to the constant terminal velocity in either of these methods is completely determined by the friction coefficient. You may only set one of the - possibilities `v_swim` *or* `f_swim` as you cannot relax to constant force - *and* constant velocity at the same time. The setting both `v_swim` and - `f_swim` to 0.0 thus disables swimming. This option applies to all + possibilities ``v_swim`` *or* ``f_swim`` as you cannot relax to constant force + *and* constant velocity at the same time. The setting both ``v_swim`` and + ``f_swim`` to 0.0 thus disables swimming. This option applies to all non-lattice-Boltzmann thermostats. Note that there is no real difference - between `v_swim` and `f_swim` since the latter may aways be chosen such that + between ``v_swim`` and ``f_swim`` since the latter may aways be chosen such that the same terminal velocity is achieved for a given friction coefficient. Parameters ---------- - 'f_swim' : :obj:`float` - Achieve a constant velocity by imposing a constant - force term 'f_swim' that is balanced by friction of a - (Langevin) thermostat. This exludes the option - 'v_swim'. - 'v_swim' : :obj:`float` - Achieve a constant velocity by imposing a constant - terminal velocity 'v_swim'. This exludes the option - 'f_swim'. - 'mode' : string, 'pusher' or 'puller' (initially 'N/A') - The LB flow field can be generated by a pushing or a - pulling mechanism, leading to change in the sign of the - dipolar flow field with respect to the direction of - motion. - 'dipole_length' : :obj:`float` - This determines the distance of the source of - propulsion from the particle's center. - 'rotational_friction' : :obj:`float` - This key can be used to set the friction that causes - the orientation of the particle to change in shear - flow. The torque on the particle is determined by - taking the cross product of the difference between the - fluid velocity at the center of the particle and at - the source point and the vector connecting the center - and source. + f_swim : :obj:`float` + Achieve a constant velocity by imposing a constant + force term ``f_swim`` that is balanced by friction of a + (Langevin) thermostat. This exludes the option ``v_swim``. + v_swim : :obj:`float` + Achieve a constant velocity by imposing a constant terminal + velocity ``v_swim``. This exludes the option ``f_swim``. + mode : :obj:`str`, \{'pusher', 'puller'\} + The LB flow field can be generated by a pushing or a + pulling mechanism, leading to change in the sign of the + dipolar flow field with respect to the direction of motion. + dipole_length : :obj:`float` + This determines the distance of the source of + propulsion from the particle's center. + rotational_friction : :obj:`float` + This key can be used to set the friction that causes + the orientation of the particle to change in shear + flow. The torque on the particle is determined by + taking the cross product of the difference between the + fluid velocity at the center of the particle and at + the source point and the vector connecting the center + and source. Notes ----- - This needs the feature ENGINE. The keys 'mode', - 'dipole_length', and 'rotational_friction' are only - available if ENGINE is used with LB or CUDA. + This needs the feature ``ENGINE``. The keys ``'mode'``, + ``'dipole_length'``, and ``'rotational_friction'`` are only + available if ``ENGINE`` is used with LB or ``CUDA``. Examples -------- @@ -1218,8 +1219,8 @@ cdef class ParticleHandle: >>> system.part.add(id=0, pos=[1,0,0],swimming={'f_swim':0.03}) >>> >>> # Usage with LB - >>> system.part.add(id=1, pos=[2,0,0],swimming={ - >>> 'f_swim':0.01, 'mode':'pusher', 'dipole_length':2.0, 'rotational_friction':20}) + >>> system.part.add(id=1, pos=[2,0,0], swimming={'f_swim': 0.01, + ... 'mode': 'pusher', 'dipole_length': 2.0, 'rotational_friction': 20}) """ @@ -1348,9 +1349,11 @@ cdef class ParticleHandle: Parameters ---------- - bond : tuple where the first element is either a bond ID of a bond - type, and the last element is the ID of the parter particle to be - bonded to. + bond : :obj:`tuple` + tuple where the first element is either a bond ID of a bond type, + and the last element is the ID of the parter particle to be bonded + to. + See Also -------- @@ -1426,9 +1429,10 @@ cdef class ParticleHandle: Parameters ---------- - _bond : tuple where the first element is either a bond ID of a bond - type, and the last element is the ID of the parter particle to be - bonded to. + _bond : :obj:`tuple` + tuple where the first element is either a bond ID of a bond type, + and the last element is the ID of the parter particle to be bonded + to. See Also @@ -1438,7 +1442,7 @@ cdef class ParticleHandle: Examples -------- >>> import espressomd - >>> from espressomd.interactions import * + >>> from espressomd.interactions import HarmonicBond >>> >>> system = espressomd.System() >>> @@ -1482,7 +1486,7 @@ cdef class ParticleHandle: -------- >>> import espressomd - >>> from espressomd.interactions import * + >>> from espressomd.interactions import HarmonicBond >>> >>> system = espressomd.System() @@ -1705,7 +1709,7 @@ class ParticleSlice(_ParticleSliceImpl): cdef class ParticleList: """ Provides access to the particles via [i], where i is the particle id. - Returns a ParticleHandle object. + Returns a :class:`ParticleHandle` object. """ @@ -1761,10 +1765,8 @@ cdef class ParticleList: for particle_number in params.keys(): params[particle_number]["id"] = particle_number IF EXCLUSIONS: - exclusions[ - particle_number] = params[ - particle_number][ - "exclusions"] + exclusions[particle_number] = params[particle_number][ + "exclusions"] del params[particle_number]["exclusions"] self._place_new_particle(params[particle_number]) IF EXCLUSIONS: @@ -1794,14 +1796,12 @@ cdef class ParticleList: -------- >>> import espressomd - >>> from espressomd.interactions import * >>> >>> system = espressomd.System() >>> >>> # add two particles >>> system.part.add(id=0, pos=(1, 0, 0)) >>> system.part.add(id=1, pos=(2, 0, 0)) - >>> Pos is mandatory, id can be omitted, in which case it is assigned automatically. Several particles can be added by passing one value per particle to each property:: @@ -1843,12 +1843,12 @@ cdef class ParticleList: # Prevent setting of contradicting attributes IF DIPOLES: if 'dip' in P and 'dipm' in P: - raise ValueError("Contradicting attributes: dip and dipm. Setting\ + raise ValueError("Contradicting attributes: dip and dipm. Setting \ dip is sufficient as the length of the vector defines the scalar dipole moment.") IF ROTATION: if 'dip' in P and 'quat' in P: - raise ValueError("Contradicting attributes: dip and quat.\ -Setting dip overwrites the rotation of the particle around the dipole axis.\ + raise ValueError("Contradicting attributes: dip and quat. \ +Setting dip overwrites the rotation of the particle around the dipole axis. \ Set quat and scalar dipole moment (dipm) instead.") # The ParticleList[]-getter ist not valid yet, as the particle @@ -1933,9 +1933,9 @@ Set quat and scalar dipole moment (dipm) instead.") Parameters ---------- fname: :obj:`str` - Filename of the target output file + Filename of the target output file types: list of :obj:`int` or the string 'all', optional (default: 'all') - A list of particle types which should be output to 'fname' + A list of particle types which should be output to 'fname' Examples -------- @@ -2041,25 +2041,22 @@ Set quat and scalar dipole moment (dipm) instead.") def select(self, *args, **kwargs): """Generates a particle slice by filtering particles via a user-defined criterion - Parameters - ---------- - Either: - - a keyword arguments in which the keys are names of particle properties - and the values are the values to filter for. E.g.,:: + Parameters: - type=0,q=1 + Either: a keyword arguments in which the keys are names of particle + properties and the values are the values to filter for. E.g.,:: - Or: + type=0,q=1 - a function taking a ParticleHandle as argument and returning True if - the particle is to be filtered for. E.g.,:: + Or: a function taking a ParticleHandle as argument and returning True if + the particle is to be filtered for. E.g.,:: - lambda p: p.pos[0]<0.5 + lambda p: p.pos[0]<0.5 Returns ------- - An instance of ParticleSlice containing the selected particles + :class:`ParticleSlice` : + An instance of :class:`ParticleSlice` containing the selected particles """ diff --git a/src/python/espressomd/shapes.py b/src/python/espressomd/shapes.py index 64576fd5673..a33d213e34c 100644 --- a/src/python/espressomd/shapes.py +++ b/src/python/espressomd/shapes.py @@ -30,18 +30,18 @@ class Cylinder(Shape, ScriptInterfaceHelper): Attributes ---------- center : array_like :obj:`float` - Coordinates of the center of the cylinder. + Coordinates of the center of the cylinder. axis : array_like :obj:`float` - Axis of the cylinder. + Axis of the cylinder. radius : :obj:`float` - Radius of the cylinder. + Radius of the cylinder. length : :obj:`float` - Length of the cylinder. + Length of the cylinder. direction : :obj:`int` - Surface orientation, for +1 the normal points - out of the mantel, for -1 it points inward. + Surface orientation, for +1 the normal points + out of the mantel, for -1 it points inward. open : :obj:`bool` - cylinder is open or has caps. + cylinder is open or has caps. """ _so_name = "Shapes::Cylinder" @@ -59,14 +59,14 @@ class Ellipsoid(Shape, ScriptInterfaceHelper): Attributes ---------- center : array_like :obj:`float` - Coordinates of the center of the ellipsoid. + Coordinates of the center of the ellipsoid. a : :obj:`float` - Semiaxis along the axis of rotational symmetry. + Semiaxis along the axis of rotational symmetry. b : :obj:`float` - Equatorial semiaxes. + Equatorial semiaxes. direction : :obj:`int` - Surface orientation, for +1 the normal points - out of the mantel, for -1 it points inward. + Surface orientation, for +1 the normal points + out of the mantel, for -1 it points inward. """ _so_name = "Shapes::Ellipsoid" @@ -114,10 +114,10 @@ class Rhomboid(Shape, ScriptInterfaceHelper): c : array_like :obj:`float` Third base vector. corner : array_like :obj:`float` - Lower left corner of the rhomboid. + Lower left corner of the rhomboid. direction : :obj:`int` - Surface orientation, for +1 the normal points - out of the mantel, for -1 it points inward. + Surface orientation, for +1 the normal points + out of the mantel, for -1 it points inward. """ _so_name = "Shapes::Rhomboid" @@ -154,12 +154,12 @@ class Sphere(Shape, ScriptInterfaceHelper): Attributes ---------- center : array_like :obj:`float` - Center of the sphere + Center of the sphere radius : :obj:`float` - Radius of the sphere. + Radius of the sphere. direction : :obj:`int` - Surface orientation, for +1 the normal points - out of the mantel, for -1 it points inward. + Surface orientation, for +1 the normal points + out of the mantel, for -1 it points inward. """ _so_name = "Shapes::Sphere" @@ -174,16 +174,16 @@ class SpheroCylinder(Shape, ScriptInterfaceHelper): Attributes ---------- center : array_like :obj:`float` - Coordinates of the center of the cylinder. + Coordinates of the center of the cylinder. axis : array_like :obj:`float` - Axis of the cylinder. + Axis of the cylinder. radius : :obj:`float` - Radius of the cylinder. + Radius of the cylinder. direction : :obj:`int` - Surface orientation, for +1 the normal points - out of the mantel, for -1 it points inward. + Surface orientation, for +1 the normal points + out of the mantel, for -1 it points inward. length : :obj:`float` - Length of the cylinder (not including the caps). + Length of the cylinder (not including the caps). """ _so_name = "Shapes::SpheroCylinder" @@ -222,16 +222,16 @@ class Torus(Shape, ScriptInterfaceHelper): Attributes ---------- center : array_like :obj:`float` - Coordinates of the center of the torus. + Coordinates of the center of the torus. normal : array_like :obj:`float` - Normal axis of the torus. + Normal axis of the torus. radius : :obj:`float` - Radius of the torus. + Radius of the torus. tube_radius : :obj:`float` - Radius of the tube. + Radius of the tube. direction : :obj:`int` - Surface orientation, for +1 the normal points - out of the mantel, for -1 it points inward. + Surface orientation, for +1 the normal points + out of the mantel, for -1 it points inward. """ _so_name = "Shapes::Torus" @@ -246,9 +246,9 @@ class Wall(Shape, ScriptInterfaceHelper): Attributes ---------- dist : :obj:`float` - Distance from the origin. + Distance from the origin. normal : array_like :obj:`int` - Normal vector of the plan (needs not to be length 1). + Normal vector of the plan (needs not to be length 1). """ _so_name = "Shapes::Wall" @@ -258,22 +258,22 @@ class Wall(Shape, ScriptInterfaceHelper): class SimplePore(Shape, ScriptInterfaceHelper): """ - Two parallel infinite planes, and a cylindrical orifice connecting them. + Two parallel infinite planes, and a cylindrical channel connecting them. The cylinder and the planes are connected by torus segments with an adjustable radius. Attributes ---------- radius: float - The radius of the pore. + The radius of the pore. length: float - The distance between the planes. + The distance between the planes. smoothing_radius: float - Radius of the torus segments + Radius of the torus segments axis: array_like - Axis of the cylinder and normal of the planes + Axis of the cylinder and normal of the planes center: array_like - Position of the center of the cylinder. + Position of the center of the cylinder. """ _so_name = "Shapes::SimplePore" diff --git a/src/python/espressomd/system.pyx b/src/python/espressomd/system.pyx index f996117303d..93d7f593887 100644 --- a/src/python/espressomd/system.pyx +++ b/src/python/espressomd/system.pyx @@ -395,10 +395,10 @@ cdef class System: Parameters ---------- d_new : :obj:`float` - New box length + New box length dir : :obj:`str`, optional - Coordinate to work on, ``"x"``, ``"y"``, ``"z"`` or ``"xyz"`` for isotropic. - Isotropic assumes a cubic box. + Coordinate to work on, ``"x"``, ``"y"``, ``"z"`` or ``"xyz"`` for isotropic. + Isotropic assumes a cubic box. """ @@ -448,11 +448,11 @@ cdef class System: Parameters ---------- phi : :obj:`float` - Angle between the z-axis and the rotation axis. + Angle between the z-axis and the rotation axis. theta : :obj:`float` - Rotation of the axis around the y-axis. + Rotation of the axis around the y-axis. alpha : :obj:`float` - How much to rotate + How much to rotate """ rotate_system(kwargs['phi'], kwargs['theta'], kwargs['alpha']) @@ -467,7 +467,7 @@ cdef class System: Parameters ---------- distance : :obj:`int` - Bond distance upto which the exclusions should be added. + Bond distance upto which the exclusions should be added. """ auto_exclusions(distance) @@ -500,8 +500,8 @@ cdef class System: """ Parameters ---------- - current_type : :obj:`int` (:attr:`espressomd.particle_data.ParticleHandle.type`) - Particle type to count the number for. + current_type : :obj:`int` (:attr:`~espressomd.particle_data.ParticleHandle.type`) + Particle type to count the number for. Returns ------- diff --git a/src/python/espressomd/thermostat.pyx b/src/python/espressomd/thermostat.pyx index 86caace2e5e..e394da73257 100644 --- a/src/python/espressomd/thermostat.pyx +++ b/src/python/espressomd/thermostat.pyx @@ -96,16 +96,18 @@ cdef class Thermostat: if thmst["type"] == "OFF": self.turn_off() if thmst["type"] == "LANGEVIN": - self.set_langevin(kT=thmst["kT"], gamma=thmst[ - "gamma"], gamma_rotation=thmst["gamma_rotation"], act_on_virtual=thmst["act_on_virtual"], seed=thmst["seed"]) + self.set_langevin(kT=thmst["kT"], gamma=thmst["gamma"], + gamma_rotation=thmst["gamma_rotation"], + act_on_virtual=thmst["act_on_virtual"], + seed=thmst["seed"]) if thmst["type"] == "LB": self.set_lb( LB_fluid=thmst["LB_fluid"], act_on_virtual=thmst["act_on_virtual"], seed=thmst["rng_counter_fluid"]) if thmst["type"] == "NPT_ISO": - self.set_npt(kT=thmst["kT"], p_diff=thmst[ - "p_diff"], piston=thmst["piston"]) + self.set_npt(kT=thmst["kT"], p_diff=thmst["p_diff"], + piston=thmst["piston"]) if thmst["type"] == "DPD": self.set_dpd(kT=thmst["kT"], seed=thmst["seed"]) @@ -216,7 +218,7 @@ cdef class Thermostat: Parameters ----------- kT : :obj:`float` - Thermal energy of the simulated heat bath. + Thermal energy of the simulated heat bath. gamma : :obj:`float` Contains the friction coefficient of the bath. If the feature ``PARTICLE_ANISOTROPY`` is compiled in then ``gamma`` can be a list @@ -371,8 +373,7 @@ cdef class Thermostat: ---------- LB_fluid : :class:`~espressomd.lb.LBFluid` or :class:`~espressomd.lb.LBFluidGPU` seed : :obj:`int` - Seed for the random number generator, required - if kT > 0. + Seed for the random number generator, required if kT > 0. act_on_virtual : :obj:`bool`, optional If ``True`` the thermostat will act on virtual sites (default). gamma : :obj:`float` diff --git a/src/python/espressomd/visualization_opengl.pyx b/src/python/espressomd/visualization_opengl.pyx index dfee75a5574..7100e0e98f2 100644 --- a/src/python/espressomd/visualization_opengl.pyx +++ b/src/python/espressomd/visualization_opengl.pyx @@ -33,161 +33,161 @@ class openGLLive: system : :class:`espressomd.system.System` window_size : array_like :obj:`int`, optional - Size of the visualizer window in pixels. + Size of the visualizer window in pixels. name : :obj:`str`, optional - The name of the visualizer window. + The name of the visualizer window. background_color : array_like :obj:`int`, optional - RGB of the background. + RGB of the background. periodic_images : array_like :obj:`int`, optional - Periodic repetitions on both sides of the box in xyzdirection. + Periodic repetitions on both sides of the box in xyzdirection. draw_box : :obj:`bool`, optional - Draw wireframe boundaries. + Draw wireframe boundaries. draw_axis : :obj:`bool`, optional - Draw xyz system axes. + Draw xyz system axes. draw_nodes : :obj:`bool`, optional - Draw node boxes. + Draw node boxes. draw_cells : :obj:`bool`, optional - Draw cell boxes. + Draw cell boxes. quality_particles : :obj:`int`, optional - The number of subdivisions for particle spheres. + The number of subdivisions for particle spheres. quality_bonds : :obj:`int`, optional - The number of subdivisions for cylindrical bonds. + The number of subdivisions for cylindrical bonds. quality_arrows : :obj:`int`, optional - The number of subdivisions for external force arrows. + The number of subdivisions for external force arrows. quality_constraints : :obj:`int`, optional - The number of subdivisions for primitive constraints. + The number of subdivisions for primitive constraints. close_cut_distance : :obj:`float`, optional - The distance from the viewer to the near clipping plane. + The distance from the viewer to the near clipping plane. far_cut_distance : :obj:`float`, optional - The distance from the viewer to the far clipping plane. + The distance from the viewer to the far clipping plane. camera_position : :obj:`str` or array_like :obj:`float`, optional - Initial camera position. ``auto`` (default) for shiftet position in z-direction. + Initial camera position. ``auto`` (default) for shiftet position in z-direction. camera_target : :obj:`str` or array_like :obj:`float`, optional - Initial camera target. ``auto`` (default) to look towards the system center. + Initial camera target. ``auto`` (default) to look towards the system center. camera_right : array_like :obj:`float`, optional - Camera right vector in system coordinates. Default is [1, 0, 0] + Camera right vector in system coordinates. Default is [1, 0, 0] particle_sizes : :obj:`str` or array_like :obj:`float` or callable, optional - auto (default): The Lennard-Jones sigma value of the - self-interaction is used for the particle diameter. - callable: A lambda function with one argument. Internally, - the numerical particle type is passed to the lambda - function to determine the particle radius. list: A list - of particle radii, indexed by the particle type. + auto (default): The Lennard-Jones sigma value of the + self-interaction is used for the particle diameter. + callable: A lambda function with one argument. Internally, + the numerical particle type is passed to the lambda + function to determine the particle radius. list: A list + of particle radii, indexed by the particle type. particle_coloring : :obj:`str`, optional - auto (default): Colors of charged particles are - specified by particle_charge_colors, neutral particles - by particle_type_colors. charge: Minimum and maximum - charge of all particles is determined by the - visualizer. All particles are colored by a linear - interpolation of the two colors given by - particle_charge_colors according to their charge. type: - Particle colors are specified by particle_type_colors, - indexed by their numerical particle type. - node: Color according to the node the particle is on. + auto (default): Colors of charged particles are + specified by particle_charge_colors, neutral particles + by particle_type_colors. charge: Minimum and maximum + charge of all particles is determined by the + visualizer. All particles are colored by a linear + interpolation of the two colors given by + particle_charge_colors according to their charge. type: + Particle colors are specified by particle_type_colors, + indexed by their numerical particle type. + node: Color according to the node the particle is on. particle_type_colors : array_like :obj:`float`, optional - Colors for particle types. + Colors for particle types. particle_type_materials : :obj:`str`, optional - Materials of the particle types. + Materials of the particle types. particle_charge_colors : array_like :obj:`float`, optional - Two colors for min/max charged particles. + Two colors for min/max charged particles. draw_constraints : :obj:`bool`, optional - Enables constraint visualization. For simple constraints - (planes, spheres and cylinders), OpenGL primitives are - used. Otherwise, visualization by rasterization is used. + Enables constraint visualization. For simple constraints + (planes, spheres and cylinders), OpenGL primitives are + used. Otherwise, visualization by rasterization is used. rasterize_pointsize : :obj:`float`, optional - Point size for the rasterization dots. + Point size for the rasterization dots. rasterize_resolution : :obj:`float`, optional - Accuracy of the rasterization. + Accuracy of the rasterization. quality_constraints : :obj:`int`, optional - The number of subdivisions for primitive constraints. + The number of subdivisions for primitive constraints. constraint_type_colors : array_like :obj:`float`, optional - Colors of the constaints by type. + Colors of the constaints by type. constraint_type_materials : array_like :obj:`str`, optional - Materials of the constraints by type. + Materials of the constraints by type. draw_bonds : :obj:`bool`, optional - Enables bond visualization. + Enables bond visualization. bond_type_radius : array_like :obj:`float`, optional - Radii of bonds by type. + Radii of bonds by type. bond_type_colors : array_like :obj:`float`, optional - Color of bonds by type. + Color of bonds by type. bond_type_materials : array_like :obj:`float`, optional - Materials of bonds by type. + Materials of bonds by type. ext_force_arrows : :obj:`bool`, optional - Enables external force visualization. + Enables external force visualization. ext_force_arrows_type_scale : array_like :obj:`float`, optional - List of scale factors of external force arrows for different particle types. + List of scale factors of external force arrows for different particle types. ext_force_arrows_type_colors : array_like :obj:`float`, optional - Colors of ext_force arrows for different particle types. + Colors of ext_force arrows for different particle types. ext_force_arrows_type_materials : array_like :obj:`float`, optional - Materils of ext_force arrows for different particle types. + Materils of ext_force arrows for different particle types. ext_force_arrows_type_radii : array_like :obj:`float`, optional - List of arrow radii for different particle types. + List of arrow radii for different particle types. force_arrows : :obj:`bool`, optional - Enables particle force visualization. + Enables particle force visualization. force_arrows_type_scale : array_like :obj:`float`, optional - List of scale factors of particle force arrows for different particle types. + List of scale factors of particle force arrows for different particle types. force_arrows_type_colors : array_like :obj:`float`, optional - Colors of particle force arrows for different particle types. + Colors of particle force arrows for different particle types. force_arrows_type_materials : array_like :obj:`float`, optional - Materials of particle force arrows for different particle types. + Materials of particle force arrows for different particle types. force_arrows_type_radii : array_like :obj:`float`, optional - List of arrow radii for different particle types. + List of arrow radii for different particle types. velocity_arrows : :obj:`bool`, optional - Enables particle velocity visualization. + Enables particle velocity visualization. velocity_arrows_type_scale : array_like :obj:`float`, optional - List of scale factors of particle velocity arrows for different particle types. + List of scale factors of particle velocity arrows for different particle types. velocity_arrows_type_colors : array_like :obj:`float`, optional - Colors of particle velocity arrows for different particle types. + Colors of particle velocity arrows for different particle types. velocity_arrows_type_materials : array_like :obj:`float`, optional - Materials of particle velocity arrows for different particle types. + Materials of particle velocity arrows for different particle types. velocity_arrows_type_radii : array_like :obj:`float`, optional - List of arrow radii for different particle types. + List of arrow radii for different particle types. director_arrows : :obj:`bool`, optional - Enables particle director visualization. + Enables particle director visualization. director_arrows_type_scale : :obj:`float`, optional - Scale factor of particle director arrows for different particle types. + Scale factor of particle director arrows for different particle types. director_arrows_type_colors : array_like :obj:`float`, optional - Colors of particle director arrows for different particle types. + Colors of particle director arrows for different particle types. director_arrows_type_materials : array_like :obj:`float`, optional - Materials of particle director arrows for different particle types. + Materials of particle director arrows for different particle types. director_arrows_type_radii : array_like :obj:`float`, optional - List of arrow radii for different particle types. + List of arrow radii for different particle types. drag_enabled : :obj:`bool`, optional - Enables mouse-controlled particles dragging (Default: False) + Enables mouse-controlled particles dragging (Default: False) drag_force : :obj:`bool`, optional - Factor for particle dragging + Factor for particle dragging LB_draw_nodes : :obj:`bool`, optional - Draws a lattice representation of the LB nodes that are no boundaries. + Draws a lattice representation of the LB nodes that are no boundaries. LB_draw_node_boundaries : :obj:`bool`, optional - Draws a lattice representation of the LB nodes that are boundaries. + Draws a lattice representation of the LB nodes that are boundaries. LB_draw_boundaries : :obj:`bool`, optional - Draws the LB shapes. + Draws the LB shapes. LB_draw_velocity_plane : :obj:`bool`, optional - Draws LB node velocity arrows specified by LB_plane_axis, LB_plane_dist, LB_plane_ngrid. + Draws LB node velocity arrows specified by LB_plane_axis, LB_plane_dist, LB_plane_ngrid. light_pos : array_like :obj:`float`, optional - If auto (default) is used, the light is placed dynamically in - the particle barycenter of the system. Otherwise, a fixed - coordinate can be set. + If auto (default) is used, the light is placed dynamically in + the particle barycenter of the system. Otherwise, a fixed + coordinate can be set. light_colors : array_like :obj:`float`, optional - Three lists to specify ambient, diffuse and specular light colors. + Three lists to specify ambient, diffuse and specular light colors. light_brightness : :obj:`float`, optional - Brightness (inverse constant attenuation) of the light. + Brightness (inverse constant attenuation) of the light. light_size : :obj:`float`, optional - Size (inverse linear attenuation) of the light. If auto - (default) is used, the light size will be set to a reasonable - value according to the box size at start. + Size (inverse linear attenuation) of the light. If auto + (default) is used, the light size will be set to a reasonable + value according to the box size at start. spotlight_enabled : :obj:`bool`, optional - If set to True (default), it enables a spotlight on the - camera position pointing in look direction. + If set to True (default), it enables a spotlight on the + camera position pointing in look direction. spotlight_colors : array_like :obj:`float`, optional - Three lists to specify ambient, diffuse and specular spotlight colors. + Three lists to specify ambient, diffuse and specular spotlight colors. spotlight_angle : :obj:`float`, optional - The spread angle of the spotlight in degrees (from 0 to 90). + The spread angle of the spotlight in degrees (from 0 to 90). spotlight_brightness : :obj:`float`, optional - Brightness (inverse constant attenuation) of the spotlight. + Brightness (inverse constant attenuation) of the spotlight. spotlight_focus : :obj:`float`, optional - Focus (spot exponent) for the spotlight from 0 (uniform) to 128. + Focus (spot exponent) for the spotlight from 0 (uniform) to 128. """ @@ -502,8 +502,7 @@ class openGLLive: self.screenshot_initialized = True self._init_opengl() - # CREATE BUFFERS THAT CAN BE LARGER THAN THE SCREEN - # FRAME BUFFER + # CREATE BUFFERS THAT CAN BE LARGER THAN THE SCREEN FRAME BUFFER fbo = OpenGL.GL.glGenFramebuffers(1) OpenGL.GL.glBindFramebuffer(OpenGL.GL.GL_FRAMEBUFFER, fbo) # COLOR BUFFER @@ -935,17 +934,15 @@ class openGLLive: def _draw_nodes(self): for n in self.node_box_origins: draw_box( - n, self.local_box_l, self.node_box_color, self.materials[ - 'transparent1'], - 1.5 * self.line_width_fac) + n, self.local_box_l, self.node_box_color, + self.materials['transparent1'], 1.5 * self.line_width_fac) def _draw_cells(self): for n in self.node_box_origins: for c in self.cell_box_origins: draw_box( - c + n, self.cell_size, self.cell_box_color, self.materials[ - 'transparent1'], - 0.75 * self.line_width_fac) + c + n, self.cell_size, self.cell_box_color, + self.materials['transparent1'], 0.75 * self.line_width_fac) def _draw_lb_grid(self): a = self.lb_params['agrid'] @@ -1771,8 +1768,8 @@ class openGLLive: OpenGL.GLUT.glutInitDisplayMode( OpenGL.GLUT.GLUT_DOUBLE | OpenGL.GLUT.GLUT_RGB | OpenGL.GLUT.GLUT_DEPTH) - OpenGL.GLUT.glutInitWindowSize(self.specs['window_size'][ - 0], self.specs['window_size'][1]) + OpenGL.GLUT.glutInitWindowSize(self.specs['window_size'][0], + self.specs['window_size'][1]) OpenGL.GLUT.glutCreateWindow(b"ESPResSo visualization") @@ -1838,10 +1835,7 @@ class openGLLive: OpenGL.GL.glLightfv( OpenGL.GL.GL_LIGHT1, OpenGL.GL.GL_POSITION, - [0, - 0, - 0, - 1]) + [0, 0, 0, 1]) OpenGL.GL.glLightfv( OpenGL.GL.GL_LIGHT1, @@ -1861,9 +1855,7 @@ class openGLLive: OpenGL.GL.glLightfv( OpenGL.GL.GL_LIGHT1, OpenGL.GL.GL_SPOT_DIRECTION, - [1.0, - 1.0, - 1.0]) + [1.0, 1.0, 1.0]) OpenGL.GL.glLightf(OpenGL.GL.GL_LIGHT1, OpenGL.GL.GL_SPOT_EXPONENT, self.specs['spotlight_focus']) From de3d08f6357f94126201c079b557940b6106d0a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Tue, 30 Jul 2019 16:24:41 +0200 Subject: [PATCH 2/3] Fix regression --- src/python/espressomd/electrostatics.pyx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/python/espressomd/electrostatics.pyx b/src/python/espressomd/electrostatics.pyx index bc28cdc10ae..f13d7f907a1 100644 --- a/src/python/espressomd/electrostatics.pyx +++ b/src/python/espressomd/electrostatics.pyx @@ -55,12 +55,12 @@ IF ELECTROSTATICS == 1: cdef class ElectrostaticInteraction(actors.Actor): def _tune(self): raise Exception( - "Subclasses of ElectrostaticInteraction must define the _tune()" - "method or chosen method does not support tuning.") + "Subclasses of ElectrostaticInteraction must define the " + "_tune() method or chosen method does not support tuning.") def _set_params_in_es_core(self): raise Exception( - "Subclasses of ElectrostaticInteraction must define the" + "Subclasses of ElectrostaticInteraction must define the " "_set_params_in_es_core() method.") def _deactivate_method(self): From d0462fb5e700c1aba83648ba08b01ab97d7be941 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jean-No=C3=ABl=20Grad?= Date: Wed, 31 Jul 2019 11:29:47 +0200 Subject: [PATCH 3/3] Apply suggestions from code review --- src/python/espressomd/collision_detection.pyx | 3 ++- src/python/espressomd/particle_data.pyx | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/src/python/espressomd/collision_detection.pyx b/src/python/espressomd/collision_detection.pyx index 2f3aa6968f6..f51b292958b 100644 --- a/src/python/espressomd/collision_detection.pyx +++ b/src/python/espressomd/collision_detection.pyx @@ -95,7 +95,8 @@ class CollisionDetection(ScriptInterfaceHelper): three_particle_binding_angle_resolution : :obj:`int` Resolution for the angular bonds (mode ``"bind_three_particles"``). - Resolution+1 bonds are needed to accommodate the case of a 180 degrees + Resolution+1 bonds are needed to accommodate the case of 180 degrees + angles """ diff --git a/src/python/espressomd/particle_data.pyx b/src/python/espressomd/particle_data.pyx index 16264826ac5..3879286bf91 100644 --- a/src/python/espressomd/particle_data.pyx +++ b/src/python/espressomd/particle_data.pyx @@ -2046,12 +2046,12 @@ Set quat and scalar dipole moment (dipm) instead.") Either: a keyword arguments in which the keys are names of particle properties and the values are the values to filter for. E.g.,:: - type=0,q=1 + system.part.select(type=0, q=1) Or: a function taking a ParticleHandle as argument and returning True if the particle is to be filtered for. E.g.,:: - lambda p: p.pos[0]<0.5 + system.part.select(lambda p: p.pos[0] < 0.5) Returns -------