clean API pages batch 1to4 (#4999)

* clean API pages batch 1to4

* Address PR review comments

Author: namiroues

package/doc/sphinx/source/documentation_pages/analysis_modules.rst

@@ -2,51 +2,40 @@
 
 .. module:: MDAnalysis.analysis
 
+.. _analysis-label:
+
 ****************
 Analysis modules
 ****************
 
-The :mod:`MDAnalysis.analysis` module contains code to carry out specific
-analysis functionality for MD trajectories.  It is based on the core
-functionality (i.e. trajectory I/O, selections etc). The analysis modules can
-be used as examples for how to use MDAnalysis but also as working code for
-research projects; typically all contributed code has been used by the authors
-in their own work.
-
-Getting started with analysis
-=============================
+The :mod:`MDAnalysis.analysis` module provides a wide collection of analysis tools for 
+molecular dynamics trajectories. These modules build upon MDAnalysis core functionality 
+(trajectory I/O, selections, etc.) and are designed both for reuse in research workflows 
+and as examples of using the MDAnalysis API. Each module typically defines an analysis 
+class that follows a standard interface.
 
-.. SeeAlso::
+See the `User Guide Analysis section`_ for interactive examples and additional context.
 
-   The `User Guide: Analysis`_ contains extensive documentation of the analysis
-   capabilities with user-friendly examples.
+.. _User Guide Analysis section: https://userguide.mdanalysis.org/stable/examples/analysis/README.html   
 
-.. _`User Guide: Analysis`:
-   https://userguide.mdanalysis.org/stable/examples/analysis/README.html   
 
-Using the analysis classes
---------------------------
+Getting started with analysis
+=============================
 
-Most analysis tools in MDAnalysis are written as a single class. An analysis
-usually follows the same pattern:
+Most analysis tools are implemented as single classes and follow this usage pattern:
 
-#. Import the desired module, since analysis modules are not imported 
-   by default.
-#. Initialize the analysis class instance from the previously imported module.   
-#. Run the analysis with the :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`
-   method, optionally for specific trajectory slices.
-#. Access the analysis from the
-   :attr:`~MDAnalysis.analysis.base.AnalysisBase.results` attribute
+#. Import the module (e.g., :mod:`MDAnalysis.analysis.rms`).
+#. Initialize the analysis class with the required arguments.
+#. Run the analysis with :meth:`~MDAnalysis.analysis.base.AnalysisBase.run`.
+#. Access results via the :attr:`~MDAnalysis.analysis.base.AnalysisBase.results` attribute.
 
 .. code-block:: python
 
    from MDAnalysis.analysis import ExampleAnalysisModule  # (e.g. RMSD)
-
    analysis_obj = ExampleAnalysisModule.AnalysisClass(universe, ...)
    analysis_obj.run(start=start_frame, stop=stop_frame, step=step)
    print(analysis_obj.results)
 
-
 Please see the individual module documentation for any specific caveats 
 and also read and cite the reference papers associated with these algorithms.
 
@@ -95,10 +84,8 @@ for maximum available on your machine):
    rmsd = RMSD(u, ref, select='backbone')
    rmsd.run(backend='multiprocessing', n_workers=multiprocessing.cpu_count())
 
-For now, you have to be explicit and specify both ``backend`` and ``n_workers``,
-since the feature is new and there are no good defaults for it. For example,
-if you specify a too big `n_workers`, and your trajectory frames are big,
-you might get and out-of-memory error when executing your run.
+Be explicit and specify both ``backend`` and ``n_workers``. Choosing too many 
+workers or using large trajectory frames may lead to an out-of-memory error.
 
 You can also implement your own backends -- see :mod:`MDAnalysis.analysis.backends`.
 

package/doc/sphinx/source/documentation_pages/overview.rst

@@ -1,219 +1,48 @@
 .. _overview-label:
 
 ==========================
- Overview over MDAnalysis
+ Overview of MDAnalysis
 ==========================
 
-**MDAnalysis** is a Python package that provides classes to access
-data in molecular dynamics trajectories. It is object oriented so it
-treats atoms, groups of atoms, trajectories, etc as different
-objects. Each object has a number of operations defined on itself
-(also known as "methods") and also contains values describing the
-object ("attributes"). For example, a
-:class:`~MDAnalysis.core.groups.AtomGroup` object has a
-:meth:`~MDAnalysis.core.groups.AtomGroup.center_of_mass` method that
-returns the center of mass of the group of atoms. It also contains an
-attribute called :attr:`~MDAnalysis.core.groups.AtomGroup.residues`
-that lists all the residues that belong to the group. Using methods
-such as :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms`
-(which uses `CHARMM-style`_ atom :ref:`selection-commands-label`) one
-can create new objects (in this case, another
-:class:`~MDAnalysis.core.groups.AtomGroup`).
+MDAnalysis is a Python package for the analysis of molecular dynamics simulations. 
+It provides an object-oriented interface to molecular structures and trajectories, 
+with direct access to atomic coordinates as :class:`numpy.ndarray` objects for seamless 
+integration with `NumPy`_ and `SciPy`_.
 
-A typical usage pattern is to iterate through a trajectory and analyze
-coordinates for every frame. In the following example the end-to-end distance
-of a protein and the radius of gyration of the backbone atoms are calculated::
+This page gives a high-level overview of the most important public classes and modules. 
+For usage examples and tutorials, refer to the `User Guide`_.
 
-    import MDAnalysis as mda
-    from MDAnalysis.tests.datafiles import PSF,DCD  # test trajectory
-    import numpy.linalg
-    u = mda.Universe(PSF,DCD)  # always start with a Universe
-    nterm = u.select_atoms('segid 4AKE and name N')[0]  # can access structure via segid (s4AKE) and atom name
-    cterm = u.select_atoms('segid 4AKE and name C')[-1]  # ... takes the last atom named 'C'
-    bb = u.select_atoms('protein and backbone')  # a selection (a AtomGroup)
-    for ts in u.trajectory:  # iterate through all frames
-        r = cterm.position - nterm.position  # end-to-end vector from atom positions
-        d = numpy.linalg.norm(r)   # end-to-end distance
-        rgyr = bb.radius_of_gyration()  # method of a AtomGroup; updates with each frame
-        print(f"frame = {ts.frame}: d = {d} Angstroem, Rgyr = {rgyr} Angstroem")
+.. _User Guide: https://userguide.mdanalysis.org/stable/index.html
+.. _NumPy: https://numpy.org/
+.. _SciPy: https://scipy.org/
 
+Key Classes
+===========
 
-.. _NumPy:   https://numpy.org/
-.. _CHARMM:  http://www.charmm.org/
-.. _LAMMPS:  http://lammps.sandia.gov/
-.. _NAMD:    http://www.ks.uiuc.edu/Research/namd/
-.. _Gromacs: http://www.gromacs.org/
+The core of MDAnalysis revolves around the :class:`~MDAnalysis.core.universe.Universe` class, 
+which serves as the central data structure that loads and connects topology and coordinate data.
+From a :class:`~MDAnalysis.core.universe.Universe`, users typically interact with :class:`~MDAnalysis.core.groups.AtomGroup` 
+objects — flexible collections of atoms that support structural selections and analysis operations. These selections 
+are created using `CHARMM-style`_ selection syntax via the :meth:`~MDAnalysis.core.groups.AtomGroup.select_atoms` method, 
+allowing users to query atoms based on names, residue numbers, segments, and more.
 
-.. _CHARMM-style:
-   http://www.charmm.org/documentation/c37b1/select.html
+Individual atoms are represented by the :class:`~MDAnalysis.core.groups.Atom` class, while residues and segments (or chains) are modeled using the 
+:class:`~MDAnalysis.core.groups.Residue` and :class:`~MDAnalysis.core.groups.Segment` classes, respectively. Together, these 
+classes form an intuitive, object-oriented hierarchy that makes it easy to navigate and analyze molecular systems.
 
-.. TODO: more about philosophy etc... copy and paste from paper
+.. _CHARMM-style: http://www.charmm.org/documentation/c37b1/select.html
 
-Using MDAnalysis in python
-==========================
-
-If you've installed MDAnalysis in the standard python modules location, load
-from within the interpreter::
-
- from MDAnalysis import *
-
-or ::
-
- import MDAnalysis as mda
-
-The idea behind MDAnalysis is to get trajectory data into NumPy_
-:class:`numpy.ndarray` arrays, where it can then be easily manipulated using
-all the power in NumPy_ and SciPy_.
-
-MDAnalysis works well both in scripts and in interactive use. The developers
-very much recommend using MDAnalysis from within the IPython_ Python shell.  It
-allows one to interactively explore the objects (using TAB-completion and
-online help), do analysis and immediately plot results. The examples in this manual
-are typically run from an interactive :program:`ipython` session.
-
-Invariably, a MDAnalysis session starts with loading data into the
-:class:`~MDAnalysis.core.universe.Universe` class (which can be accessed
-as :class:`MDAnalysis.Universe`)::
-
- import MDAnalysis as mda
- universe = mda.Universe(topology, trajectory)
-
-- The *topology* file lists the atoms and residues (and also their
-  connectivity). It can be a CHARMM/XPLOR/NAMD PSF file or a coordinate file
-  such as a Protein Databank Brookhaven PDB file, a CHARMM card coordinate file
-  (CRD), or a GROMOS/Gromacs GRO file.
-
-- The *trajectory* contains a list of coordinates in the order defined in the
-  *topology*. It can either be a single frame (PDB, CRD, and GRO are all read)
-  or a time series of coordinate frames such as a CHARMM/NAMD/LAMMPS DCD
-  binary file, a Gromacs XTC/TRR trajectory, or a XYZ trajectory (possibly
-  compressed with gzip or bzip2).
-
-For the remainder of this introduction we are using a short example trajectory
-that is provided with MDAnalysis (as part of the `MDAnalysis test suite`_). The
-trajectory is loaded with ::
-
-  >>> from MDAnalysis import Universe
-  >>> from MDAnalysis.tests.datafiles import PSF,DCD
-  >>> u = Universe(PSF, DCD)
-
-(The ``>>>`` signs are the Python input prompt and are not to be typed; they
-just make clear in the examples what is input and what is output.)
-
-The :class:`~MDAnalysis.core.universe.Universe` contains a number of important attributes,
-the most important ones of which is
-:attr:`~MDAnalysis.core.universe.Universe.atoms`::
-
-  >>> print(u.atoms)
-  <AtomGroup with 3341 atoms>
-
-:attr:`Universe.atoms` is a
-:class:`~MDAnalysis.core.groups.AtomGroup` and can be thought of as
-list consisting of :class:`~MDAnalysis.core.groups.Atom`
-objects. The :class:`~MDAnalysis.core.groups.Atom` is the
-elementary and fundamental object in MDAnalysis.
-
-The :attr:`MDAnalysis.Universe.trajectory` attribute gives access to the coordinates
-over time::
-
-  >>> print(u.trajectory)
-  < DCDReader '/..../MDAnalysis/tests/data/adk_dims.dcd' with 98 frames of 3341 atoms (0 fixed) >
-
-Finally, the :meth:`MDAnalysis.Universe.select_atoms` method generates a new
-:class:`~MDAnalysis.core.groups.AtomGroup` according to a selection criterion::
-
-  >>> calphas = u.select_atoms("name CA")
-  >>> print(calphas)
-  <AtomGroup with 214 atoms>
-
-as described in :ref:`selection-commands-label`.
-
-.. _SciPy: http://www.scipy.org/
-.. _IPython: https://ipython.org/
-.. _MDAnalysis test suite: https://github.com/MDAnalysis/mdanalysis/wiki/UnitTests
-
-
-Examples
-========
-
-The easiest way to get started with MDAnalysis is to read this introduction and the chapters on :ref:`topology-label` and :ref:`selection-commands-label`, then explore the package interactively in IPython_ or another interactive Python interpreter.
-
-Included trajectories
----------------------
-
-MDAnalysis comes with a number of real trajectories for testing. You
-can also use them to explore the functionality and ensure that
-everything is working properly::
-
-  import MDAnalysis as mda 
-  from MDAnalysis.tests.datafiles import PSF,DCD, PDB,XTC
-  u_dims_adk = mda.Universe(PSF,DCD)
-  u_eq_adk = mda.Universe(PDB, XTC)
-
-The PSF and DCD file are a closed-form-to-open-form transition of
-Adenylate Kinase (from [Beckstein2009]_) and the PDB+XTC file are ten
-frames from a Gromacs simulation of AdK solvated in TIP4P water with
-the OPLS/AA force field.
-
-.. [Beckstein2009] O. Beckstein, E.J. Denning, J.R. Perilla, and
-                   T.B. Woolf. Zipping and Unzipping of Adenylate
-                   Kinase: Atomistic Insights into the Ensemble of
-                   Open <--> Closed Transitions. *J Mol Biol* **394**
-                   (2009), 160--176, doi:`10.1016/j.jmb.2009.09.009`_
-
-.. _`10.1016/j.jmb.2009.09.009`: http://dx.doi.org/10.1016/j.jmb.2009.09.009
-
-Code snippets
--------------
-
-The source code distribution comes with a directory `examples`_ that
-contains a number of code snippets that show how to use certain
-aspects of MDAnalysis.
-
-For instance, there is code that shows how to
-
-* fit a trajectory to a reference structure using the QCP
-  RMSD-alignment code in :mod:`MDAnalysis.core.qcprot`
-  (`rmsfit_qcp.py`_);
-
-* do a block-averaging error analysis (`blocks.py`_);
-
-* calculate a potential profile across a membrane (`potential_profile.py`_);
-
-* do a native contact analysis using :mod:`MDAnalysis.analysis.contacts` (`nativecontacts.py`_)
-
-* get the lipid composition of the individual leaflets of a bilayer
-  using :mod:`MDAnalysis.analysis.leaflet` (`membrane-leaflets.py`_);
-
-* define the multimeric states of a number of transmembrane peptides
-  via clustering (`multimers-analysis.py`_);
-
-* convert between trajectory formats (e.g. `dcd2xtc.py`_ or `amber2dcd.py`_)
+Core modules
+============
 
-* use MDAnalysis for simple model building (`make_MthK_tetramer.py`_);
+MDAnalysis is organized into several core modules that provide specialized functionality for 
+handling and analyzing molecular dynamics data. The :mod:`MDAnalysis.core` module defines the 
+essential data structures such as :class:`~MDAnalysis.core.universe.Universe`, :class:`~MDAnalysis.core.groups.AtomGroup`, 
+and related objects. The :mod:`MDAnalysis.analysis` module contains a collection of analysis tools for tasks like RMSD calculation, 
+diffusion analysis, contact maps, and more. The :mod:`MDAnalysis.selections` module implements the flexible selection language used 
+to query atoms based on structural properties. Finally, :mod:`MDAnalysis.topology` manages topology parsing and representation, 
+supporting a wide range of file formats for loading molecular structures.
 
-and more.
 
-.. Links to the stable git repository:
 
-.. _examples:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/tree/master/examples/
 
-.. _`rmsfit_qcp.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/rmsfit_qcp.py
-.. _`blocks.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/blocks.py
-.. _`potential_profile.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/potential_profile.py
-.. _`nativecontacts.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/nativecontacts.py
-.. _`membrane-leaflets.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/membrane-leaflets.py
-.. _`multimers-analysis.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/multimers-analysis.py
-.. _`dcd2xtc.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/dcd2xtc.py
-.. _`amber2dcd.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/amber2dcd.py
-.. _`make_MthK_tetramer.py`:
-   https://github.com/MDAnalysis/MDAnalysisCookbook/blob/master/examples/make_MthK_tetramer.py

package/doc/sphinx/source/documentation_pages/topology.rst

@@ -5,11 +5,10 @@
  The topology system
 =====================
 
-As shown briefly in :ref:`overview-label`, the :class:`~MDAnalysis.core.universe.Universe` class is the primary object and core interface to molecular dynamics data in MDAnalysis.
-When loading topology information from a file, as with ::
+See :mod:`MDAnalysis.topology` for details on topology parsing, format support, and 
+the :class:`~MDAnalysis.core.topology.Topology` object.
 
-  >>> from MDAnalysis import Universe
-  >>> from MDAnalysis.tests.datafiles import PSF
-  >>> u = Universe(PSF)
+User-level documentation can be found in the `topology section of the User Guide`_.
+
+.. _topology section of the User Guide: https://userguide.mdanalysis.org/stable/topology_system.html
 
-the file is read, the contents parsed, and a :class:`~MDAnalysis.core.topology.Topology` object is constructed from these contents.