Production/Stable

* automatic exclusion of atoms with zero radius from surface analysis (this creates artefacts especially with the triangulation in GITIM) * updated documentation * Chacon-Tarazona support removed (contact developers to reintroduce it if needed) * ready for integration in MDAKits (see https://github.com/MDAnalysis/MDAKits) * version bump to 1.0.0
Marcello-Sega · Aug 6, 2024 · 99213e6 · 99213e6
1 parent 6be94f0
commit 99213e6
Show file tree

Hide file tree

Showing 25 changed files with 277 additions and 399 deletions.
diff --git a/AUTHORS.md b/AUTHORS.md
@@ -0,0 +1,7 @@
+Marcello-Sega https://api.github.com/users/Marcello-Sega
+gyorgy-hantal https://api.github.com/users/gyorgy-hantal
+balazsfabian https://api.github.com/users/balazsfabian
+elija-feigl https://api.github.com/users/elija-feigl
+JakobMichl https://api.github.com/users/JakobMichl
+iuvenis https://api.github.com/users/iuvenis
+bnovak1 https://api.github.com/users/bnovak1
diff --git a/README.md b/README.md
@@ -26,7 +26,6 @@ So far the following interface/phase identification methods have been implemente
 * GITIM 
 * SASA
 * Willard Chandler
-* Chacon Tarazona
 * DBSCAN filtering
 
 ## Supported formats
@@ -475,7 +474,5 @@ Depending on which algorithm you are using, you might also want to cite the foll
 
 [M. Sega and G. Hantal._Phys. Chem. Chem. Phys._ **29**, 18968-18974 (2017)](https://doi.org/10.1039/C7CP02918G) Phase and interface determination in computer simulations of liquid mixtures with high partial miscibility.
 
-[E. Chacón, P. Tarazona, Phys. Rev. Lett. **91**, 166103 (2003)](http://dx.doi.org/10.1103/PhysRevLett.91.166103) Intrinsic profiles beyond the capillary wave theory: A Monte Carlo study.
-
 [A. P. Willard, D. Chandler, J. Phys. Chem. B **114**,1954 (2010)](http://dx.doi.org/10.1021/jp909219k) Instantaneous Liquid Interfaces
 
diff --git a/README.rst b/README.rst
@@ -12,8 +12,8 @@ So far the following methods have been implemented:
 
 * ITIM
 * GITIM 
+* SASA
 * Willard Chandler
-* Chacon Tarazona
 * DBSCAN filtering
 
 ----

diff --git a/docs/source/ChaconTarazona.rst b/docs/source/ChaconTarazona.rst
diff --git a/docs/source/SASA.rst b/docs/source/SASA.rst
@@ -0,0 +1,18 @@
+SASA
+****
+
+.. include:: refs.rst
+
+.. automodule:: pytim.sasa
+   :members: SASA
+   :inherited-members:
+   :member-order: bysource
+   :exclude-members: LayerAtomGroup, alpha,cluster_cut, cluster_threshold_density,extra_cluster_groups,info,itim_group,max_layers,molecular,multiproc,radii_dict,save_pdb, surfaces
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
+.. raw:: html
+   :file: analytics.html
+
diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -77,16 +77,16 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.7'
+version = u'1.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.7.0'
+release = u'1.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -23,8 +23,8 @@
 
     ITIM
     GITIM
+    SASA
     WillardChandler
-    ChaconTarazona
     SimpleInterface
     observables
     datafiles

diff --git a/docs/source/install.rst b/docs/source/install.rst
@@ -17,10 +17,6 @@ The package will download all the dependencies which are needed. Prerequisites f
 
 .. code-block:: bash
 
-	pip install setuptools --user --upgrade
-	pip install numpy --user --upgrade
-	pip install cython --user --upgrade
-
 	git clone https://github.com/Marcello-Sega/pytim.git
 	cd pytim
 	python setup.py install --user
@@ -35,12 +31,22 @@ The package can also be installed directly from the Python Package Index, along
 
 .. code-block:: bash
 
-	pip install setuptools --user --upgrade
-	pip install cython --user --upgrade
-	pip install numpy --user --upgrade
-
+	git clone https://github.com/Marcello-Sega/pytim.git
+	cd pytim
 	pip install pytim --user --upgrade
 
+
+Alternatively, you can use pip (directly or as a module) to install pytim, possibly in developer/editable mode:
+
+.. code-block:: bash
+
+	git clone https://github.com/Marcello-Sega/pytim.git
+	cd pytim
+	python -m pip install -e .
+
+This way the changes in the source will be reflected immediately after restarting a python shell, avoiding the need to reinstall every time.
+
+
 Using Anaconda
 --------------
 

diff --git a/docs/source/observables.rst b/docs/source/observables.rst
@@ -6,6 +6,8 @@ Radial Distribution Functions
 #############################
 .. automodule:: pytim.observables.rdf
     :members:
+.. automodule:: pytim.observables.rdf2d
+    :members:
 
 Profiles
 ########
@@ -17,11 +19,32 @@ Time Correlation Functions
 .. autoclass:: pytim.observables.Correlator
     :members:
 
+Contact Angles
+##############
+.. autoclass:: pytim.observables.ContactAngle
+    :members:
+
+3D Distributions
+################
+.. autoclass:: pytim.observables.DistributionFunction
+    :members:
+
+Free Volume
+###########
+.. autoclass:: pytim.observables.FreeVolume
+    :members:
+
+Local Reference Frame
+#####################
+
+
 Misc
 ####
+.. autoclass:: pytim.observables.IntrinsicDistance
+    :members:
 .. autoclass:: pytim.observables.LayerTriangulation
     :members:
-.. autoclass:: pytim.observables.IntrinsicDistance
+.. autoclass:: pytim.observables.LocalReferenceFrame
     :members:
 
 

diff --git a/docs/source/quick.rst b/docs/source/quick.rst
@@ -1,15 +1,12 @@
 Pytim: Quick Tour
 *****************
 
+.. include:: refs.rst 
+
 :doc:`Pytim <quick>` is a package based on MDAnalysis_ for the identification and analysis of surface molecules in configuration files or in trajectories from molecular dynamics simulations.
 
-Although MDAnalysis_ is needed to perform the interfacial analysis, you can also use :doc:`Pytim <quick>` on top of MDTraj_ or directly online from a simulation performed using OpenMM_. For more information see the :doc:`Tutorials`.
+Although MDAnalysis_ is needed to perform the interfacial analysis, you can also use :doc:`Pytim <quick>` on top of MDTraj_ or directly online from a simulation performed using OpenMM_.
 
-.. _MDAnalysis: http://www.mdanalysis.org/
-.. _MDTraj: http://www.mdtraj.org/
-.. _OpenMM: http://www.openmm.org/
-.. _Paraview: https://www.paraview.org/
-.. _Supported_Formats: https://pythonhosted.org/MDAnalysis/documentation_pages/coordinates/init.html#id1
 
 Basic Example
 =============
@@ -63,7 +60,7 @@ where surface oxygen atoms are highlighted in blue.
    :width: 70%
    :align: center
 
-This is a very basic example, and more are given below, in the :doc:`Tutorials`, and in the documentation of the modules.
+This is a very basic example, and more are given below and in the documentation of the modules.
 
 Non-planar interfaces
 =====================
@@ -100,6 +97,37 @@ We make here the example of multiple solvation layers around glucose:
 	:width: 40%
 	:align: center
 
+SASA
+----
+
+The Solvent-Accessible-Surface-Area method of Lee and Richards has been extensively used 
+to compute the exposed surface of proteins to calculate solvation and electrostatic effects.
+However, the method can be also used to produce the list of surface-exposed atoms. In this sense,
+it is a very similar to GITIM. In the present implementation, the identification of surface atoms
+scales quasi-linear with the number of atoms.
+
+The above example for GITIM can be rewritten using :class:`~pytim.sasa.SASA` with very similar results:
+
+.. code-block:: python
+
+    import MDAnalysis as mda
+    import pytim
+    from   pytim.datafiles import GLUCOSE_PDB
+
+    u       = mda.Universe(GLUCOSE_PDB)
+    solvent = u.select_atoms('name OW')
+    glc     = u.atoms - solvent.residues.atoms
+
+    # alpha is the probe-sphere radius
+    inter = pytim.SASA(u, group=solvent, max_layers=3, alpha=2)
+
+    for i in [0,1,2]:
+        print ("Layer "+str(i),repr(inter.layers[i]))
+
+    Layer 0 <AtomGroup with 42 atoms>
+    Layer 1 <AtomGroup with 102 atoms>
+    Layer 2 <AtomGroup with 189 atoms>
+
 
 Willard-Chandler
 ----------------

diff --git a/docs/source/refs.rst b/docs/source/refs.rst
@@ -0,0 +1,8 @@
+
+.. _MDAnalysis: http://www.mdanalysis.org/
+.. _MDTraj: http://www.mdtraj.org/
+.. _OpenMM: http://www.openmm.org/
+.. _Paraview: https://www.paraview.org/
+.. _Supported_Formats: https://pythonhosted.org/MDAnalysis/documentation_pages/coordinates/init.html#id1
+
+
diff --git a/pytim/__init__.py b/pytim/__init__.py
@@ -7,7 +7,6 @@
 from .gitim import GITIM
 from .sasa import SASA
 from .willard_chandler import WillardChandler
-from .chacon_tarazona import ChaconTarazona
 from . import observables, utilities, datafiles
 from .version import __version__
 import warnings