Skip to content

Commit

Permalink
Merge #3029
Browse files Browse the repository at this point in the history 
3029: Cleanup Sphinx documentation r=fweik a=jngrad

Clean up Sphinx documentation of files affected by #3026:
- apply numpydoc style (indentation level of param descriptions, show allowed param values)
- remove duplicated docstrings, add missing words
- use LaTeX math to display equations of constraints
- fix broken Sphinx syntax (typos, unparsed `.. notes::` directives, missing links, etc.).

Co-authored-by: Jean-Noël Grad <jgrad@icp.uni-stuttgart.de>
  • Loading branch information
@bors @jngrad
bors[bot] and jngrad committed Jul 31, 2019
2 parents 88aac29 + d0462fb commit de20f8e
Show file tree
Hide file tree
Showing 21 changed files with 590 additions and 597 deletions.
7 changes: 4 additions & 3 deletions src/python/espressomd/analyze.pyx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down Expand Up @@ -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`
Expand Down
63 changes: 31 additions & 32 deletions src/python/espressomd/cellsystem.pyx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
"""

Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
"""

Expand Down Expand Up @@ -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)
Expand Down
5 changes: 3 additions & 2 deletions src/python/espressomd/cluster_analysis.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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")
Expand Down
54 changes: 30 additions & 24 deletions src/python/espressomd/collision_detection.pyx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -60,39 +60,43 @@ 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 180 degrees
angles
"""

Expand All @@ -102,8 +106,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"]]
Expand Down Expand Up @@ -135,12 +140,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)
Expand Down Expand Up @@ -189,7 +195,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(),)

Expand Down
3 changes: 1 addition & 2 deletions src/python/espressomd/comfixed.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading

0 comments on commit de20f8e

Please sign in to comment.