Skip to content

Commit

Permalink
Cleanup Sphinx documentation
Browse files Browse the repository at this point in the history
Fix incorrect Sphinx reST syntax and correct typos.
  • Loading branch information
jngrad committed Mar 6, 2020
1 parent 65274a5 commit 092fefe
Show file tree
Hide file tree
Showing 7 changed files with 69 additions and 45 deletions.
16 changes: 8 additions & 8 deletions src/python/espressomd/accumulators.py
Original file line number Diff line number Diff line change
Expand Up @@ -26,18 +26,18 @@ class MeanVarianceCalculator(ScriptInterfaceHelper):
Parameters
----------
obs : Instance of :class:`espressomd.observables.Observable`.
obs : :class:`espressomd.observables.Observable`
delta_N : :obj:`int`
Number of timesteps between subsequent samples for the auto update mechanism.
Methods
-------
update
update()
Update the accumulator (get the current values from the observable).
get_mean
get_mean()
Returns the samples mean values of the respective observable with which the
accumulator was initialized.
get_variance
get_variance()
Returns the samples variance for the observable.
"""
Expand All @@ -58,17 +58,17 @@ class TimeSeries(ScriptInterfaceHelper):
Parameters
----------
obs : Instance of :class:`espressomd.observables.Observable`.
obs : :class:`espressomd.observables.Observable`
delta_N : :obj:`int`
Number of timesteps between subsequent samples for the auto update mechanism.
Methods
-------
update
update()
Update the accumulator (get the current values from the observable).
time_series
time_series()
Returns the recorded values of the observable.
clear
clear()
Clear the data
"""
Expand Down
52 changes: 33 additions & 19 deletions src/python/espressomd/cluster_analysis.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,27 +21,24 @@
@script_interface_register
class Cluster(ScriptInterfaceHelper):

"""Class representing a cluster of particles
"""Class representing a cluster of particles.
Methods
-------
particle_ids()
Returns list of particle ids in the cluster
particles()
Returns an instance of ParticleSlice containing the particles in the cluster
size()
Returns the number of particles in the cluster
center_of_mass()
center of mass of the cluster
Center of mass of the cluster
longest_distance()
Longest distance between any combination of two particles in the cluster
fractal_dimension(dr=None)
estimates the cluster's fractal dimension by fitting the number of
Estimates the cluster's fractal dimension by fitting the number of
particles :math:`n` in spheres of growing radius around the center of mass
to :math:`c*r_g^d`, where :math:`r_g` is the radius of gyration of the
particles within the sphere, and :math:`d` is the fractal dimension.
Expand All @@ -52,13 +49,14 @@ class Cluster(ScriptInterfaceHelper):
Parameters
----------
dr:
dr: :obj:`float`
Minimum increment for the radius of the spheres.
Returns
-------
:obj:`tuple`:
Fractal_dimension, mean_square_residual.
Fractal dimension and mean square residual.
"""
_so_name = "ClusterAnalysis::Cluster"
_so_bind_methods = ("particle_ids", "size", "longest_distance",
Expand All @@ -67,6 +65,14 @@ class Cluster(ScriptInterfaceHelper):
_so_creation_policy = "LOCAL"

def particles(self):
"""
Get particles in the cluster.
Returns
-------
:class:`espressomd.particle_data.ParticleSlice`
"""
return ParticleSlice(self.particle_ids())


Expand All @@ -75,9 +81,9 @@ class ClusterStructure(ScriptInterfaceHelper):

"""Cluster structure of a simulation system, and access to cluster analysis
Attributes
Parameters
----------
pair_criterion: classes derived from ``_PairCriterion``
pair_criterion: :class:`espressomd.pair_criteria._PairCriterion`
Criterion to decide whether two particles are neighbors.
"""
Expand Down Expand Up @@ -117,18 +123,25 @@ def cluster_ids(self):
return self.call_method("cluster_ids")

def cid_for_particle(self, p):
"""Returns cluster id for the particle (passed as ParticleHandle or particle id)"""
"""Returns cluster id for the particle.
Parameters
----------
p : :obj:`espressomd.particle_data.ParticleHandle` or :obj:`int` containing the particle id
Particle.
"""
if isinstance(p, ParticleHandle):
return self.call_method("cid_for_particle", pid=p.id)
if isinstance(p, int):
return self.call_method("cid_for_particle", pid=p)
else:
raise TypeError(
"The particle has to be passed as instance of Particle handle or as an integer particle id")
raise TypeError(
"The particle has to be passed as instance of ParticleHandle or as an integer particle id")

@property
def clusters(self):
"""Gives access to the clusters in the cluster structure via an instance of :any:`Clusters`."""
"""Gives access to the clusters in the cluster structure via an
instance of :class:`Clusters`."""
return self._clusters


Expand All @@ -138,13 +151,14 @@ class Clusters:
Access is as follows:
* Number of clusters: len(clusters)
* Access a cluster via its id: clusters[id]
* Iterate over clusters::
* number of clusters: ``len(clusters)``
* access a cluster via its id: ``clusters[id]``
* iterate over clusters::
for c in clusters:
where c will be a tuple containing the cluster id and the cluster object
where ``c`` will be a tuple containing the cluster id and the cluster object.
"""

def __init__(self, cluster_structure):
Expand Down
29 changes: 18 additions & 11 deletions src/python/espressomd/pair_criteria.py
Original file line number Diff line number Diff line change
Expand Up @@ -48,11 +48,13 @@ class DistanceCriterion(_PairCriterion):
"""Pair criterion returning true, if particles are closer than a cutoff.
Periodic boundaries are treated via minimum image convention.
The following parameters can be passed to the constructor, changed via set_params()
and retrieved via get_params()
The following parameters can be passed to the constructor, changed via
``set_params()`` and retrieved via ``get_params()``.
Parameters
----------
cut_off : :obj:`float`
distance cut off for the criterion
distance cutoff for the criterion
"""
_so_name = "PairCriteria::DistanceCriterion"
_so_creation_policy = "LOCAL"
Expand All @@ -61,16 +63,19 @@ class DistanceCriterion(_PairCriterion):
@script_interface_register
class EnergyCriterion(_PairCriterion):

"""Pair criterion returning true, if the short range energy between the particles is >= the cutoff
"""Pair criterion returning true, if the short range energy between the
particles is superior or equal to the cutoff.
Be aware that the short range energy contains the short range part of dipolar and electrostatic interactions,
but not the long range part.
Be aware that the short range energy contains the short range part of
dipolar and electrostatic interactions, but not the long range part.
The following parameters can be passed to the constructor, changed via set_params()
and retrieved via get_params()
The following parameters can be passed to the constructor, changed via
``set_params()`` and retrieved via ``get_params()``.
Parameters
----------
cut_off : :obj:`float`
energy cut off for the criterion
energy cutoff for the criterion
"""
_so_name = "PairCriteria::EnergyCriterion"
_so_creation_policy = "LOCAL"
Expand All @@ -81,9 +86,11 @@ class BondCriterion(_PairCriterion):

"""Pair criterion returning true, if a pair bond of given type exists between them
The following parameters can be passed to the constructor, changed via set_params()
and retrieved via get_params()
The following parameters can be passed to the constructor, changed via
``set_params()`` and retrieved via ``get_params()``.
Parameters
----------
bond_type : :obj:`int`
numeric type of the bond
"""
Expand Down
3 changes: 2 additions & 1 deletion src/python/espressomd/particle_data.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -1416,7 +1416,8 @@ cdef class ParticleHandle:
Parameters
----------
_bond : bond to be deleted
_bond :
bond to be deleted
See Also
--------
Expand Down
6 changes: 3 additions & 3 deletions src/python/espressomd/polymer.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -180,14 +180,14 @@ def setup_diamond_polymer(system=None, bond=None, MPC=0,
Parameters
----------
system : instance of :obj:`espressomd.system.System`, required
system : :class:`espressomd.system.System`, required
System to which the particles will be added.
bond : instance of :obj:`espressomd.interactions.BondedInteraction`, required if ``no_bonds == False``
bond : :class:`espressomd.interactions.BondedInteraction`, required if ``no_bonds == False``
The bond to be created between monomers. Should be compatible with the
spacing ``system.box_l[0]*(0.25 * sqrt(3))/(MPC + 1)`` between monomers.
no_bonds : :obj:`bool`, optional
If True, the particles will only be placed in the system but not connected by bonds.
In that case, the `bond` argument can be omitted. Defaults to ``False``.
In that case, the ``bond`` argument can be omitted. Defaults to ``False``.
MPC : :obj:`int`, optional
Monomers per chain, where chain refers to the connection
between the 8 lattice nodes of the diamond lattice.
Expand Down
2 changes: 1 addition & 1 deletion src/python/espressomd/shapes.py
Original file line number Diff line number Diff line change
Expand Up @@ -259,7 +259,7 @@ class HollowConicalFrustum(Shape, ScriptInterfaceHelper):
r2: :obj:`float`
Radius r2.
length: :obj:`float`
Length of the conical frustum along `axis`.
Length of the conical frustum along ``axis``.
axis: (3,) array_like of :obj:`float`
Symmetry axis.
center: (3,) array_like of :obj:`float`
Expand Down
6 changes: 4 additions & 2 deletions src/python/espressomd/utils.pyx
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@ cdef List[int] create_int_list_from_python_object(obj):
Parameters
----------
obj : python object which supports subscripts
obj :
python object which supports subscripts
"""
cdef List[int] il
Expand Down Expand Up @@ -302,7 +303,8 @@ def is_valid_type(value, t):


def requires_experimental_features(reason):
"""Class decorator which makes instantiation conditional on EXPERIMENTAL_FEATURES being defined in myconfig.hpp."""
"""Class decorator which makes instantiation conditional on
``EXPERIMENTAL_FEATURES`` being defined in myconfig.hpp."""

def exception_raiser(self, *args, **kwargs):
raise Exception(
Expand Down

0 comments on commit 092fefe

Please sign in to comment.