Merge pull request #93 from luigibonati/fix_doc

Fix documentation

docs/autosummary/mlcolvar.cvs.BaseCV.rst

@@ -0,0 +1,46 @@
+mlcolvar.cvs.BaseCV
+===================
+
+.. currentmodule:: mlcolvar.cvs
+
+.. autoclass:: BaseCV
+   :members:                                   
+   :show-inheritance:                           
+   :inherited-members: Module,LightningModule                       
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~BaseCV.__init__
+      ~BaseCV.configure_optimizers
+      ~BaseCV.forward
+      ~BaseCV.forward_cv
+      ~BaseCV.initialize_blocks
+      ~BaseCV.initialize_transforms
+      ~BaseCV.parse_options
+      ~BaseCV.setup
+      ~BaseCV.test_step
+      ~BaseCV.validation_step
+
+
+
+
+..
+   
+
+   .. rubric:: Attributes
+
+   .. autosummary::
+
+      ~BaseCV.example_input_array
+      ~BaseCV.n_cvs
+      ~BaseCV.optimizer_name
+
+
+
+

docs/contributing.rst

@@ -24,6 +24,12 @@ implementation path from the start. Then
       cd mlcolvar
       pip install -e .
 
+4. In order to perform the regtests and build the documentation you need to install additional packages:
+
+    .. code-block:: bash
+
+      pip install mlcolvar[docs,test]
+
 Once your environment is set up you are ready to implement your changes.
 
 
@@ -87,13 +93,19 @@ and simply run
     python myfile.py
 
 Finally, when modifying the documentation (especially when using reStructuredText syntax), it is a very good idea to build the
-documentation to check the result. To do this you will need to install these additional packages
+documentation to check the result. To do this you will need to install these additional packages:
 
 .. code-block:: bash
 
     pip install furo nbsphinx sphinx-copybutton
 
-and then run the commands
+or more simply using:
+
+.. code-block:: bash
+
+    pip install mlcolvar[doc]
+
+Then, you can build the docs via the command
 
 .. code-block:: bash
 

docs/installation.rst

@@ -52,6 +52,13 @@ modifications automatically installed
 
     pip install -e .
 
+Furthermore, if you want to check that the library is working properly, you can perform the regtests by installing the optional dependencies and then executing `pytest` in the mlcolvar folder.
+
+.. code-block:: bash
+
+    pip install mlcolvar[test]
+    pytest
+
 
 Create a virtual environment
 ----------------------------

docs/notebooks/tutorials/cvs_DeepTICA.ipynb

@@ -40,23 +40,17 @@
     "TICA is a dimensionality reduction method that projects input features into orthogonal linear combinations that are maximally autocorrelated. Consequently, it can be used to find the directions along which the system relaxes most slowly. In a rare event scenario, these slow modes are related to the rare transitions between long-lived metastable states. It has also been shown that the independent components approximate the eigenfunctions of the transfer operator. This operator is responsible for the evolution of the probability density toward the Boltzmann distribution, and its eigenfunctions represent the slow modes that must be accelerated to speed up the convergence.\n",
     "\n",
     "For a given lag time $\\tau$, we can construct the time-lagged covariance matrix from the mean-free features $\\mathbf{\\delta x}$ as:\n",
-    "\\begin{equation}\n",
-    "    \\mathbf{C}_\\tau = \\mathbb{E}[(\\mathbf{\\delta x}_t)\\ (\\mathbf{\\delta x}_{t+\\tau})^T]\n",
-    "\\end{equation}\n",
+    "$$ \\mathbf{C}_\\tau = \\mathbb{E}[(\\mathbf{\\delta x}_t)\\ (\\mathbf{\\delta x}_{t+\\tau})^T]$$\n",
     " as well as the covariance matrix $\\mathbf{C}_0=\\mathbf{C}$ from Eq.~\\ref{eq:covariance}. Here we denote the data also with the time information: $\\mathbf{x}_t = \\mathbf{x}(\\mathbf{R}(t))$. Then the independent components are obtained from the solution of the following generalized eigenvalue problem: \n",
-    "\\begin{equation}\n",
-    "    \\mathbf{C}_\\tau\\mathbf{v}_i = \\mathbf{C}_0\\lambda_i^{(tica)} \\mathbf{v}_i\n",
-    "\\end{equation}\n",
+    "$$\\mathbf{C}_\\tau\\mathbf{v}_i = \\mathbf{C}_0\\lambda_i^{(tica)} \\mathbf{v}_i$$\n",
     "where the eigenvalues $\\lambda_i^{(tica)}$ measure the autocorrelation of the $\\mathbf{v}_i$ component which can be also related to an implied time scale $t_i = -\\tau / \\ln{\\lambda_i^{(tica)}}$.\n",
     "\n",
     "**Neural network basis functions for TICA**\n",
     "\n",
     "Similarly to Deep-LDA, we can consider a nonlinear generalization by first applying a neural network to the inputs and then projecting along the TICA components. This corresponds to using NNs as basis functions for the variational principle of the transfer operator. In fact, the longer the autocorrelation of the variables, the more accurately they represent its eigenfunctions. For this purpose, similar architectures have been proposed. In the Variational Approach for Markov processes (VAMP) framework this was used as input for building Markov State Models, whereas in the state-free reversible VAMPnets (SRV) it was used for CVs discovery. Finally, the Deep-TICA method has extended it also to extract CVs from biased simulations.\n",
     "\n",
     "In all these methods, the dataset is composed of pairs of time-lagged configurations $\\{\\mathbf{ x}_{t},\\mathbf{ x}_{t+\\tau}\\}$ which are transformed by a NN into a space of nonlinear basis functions $\\{\\mathbf{f}(\\mathbf{ x}_{t}),\\mathbf{f}(\\mathbf{ x}_{t+\\tau})\\}$. The parameters of the network are then optimized to maximize the TICA eigenvalues. Typically the sum of squares (which correspond also to the so-called VAMP-2 score) is used in place of eq.~\\ref{eq:loss-autocorr}, but any monotonic function could be in principle used (e.g. the sum of implied timescales).\n",
-    "\\begin{equation}\n",
-    "\\mathcal{L}_{DeepTICA}=- \\sum_{i} (\\lambda_i^{(tica)})^2\n",
-    "\\end{equation}"
+    "$$\\mathcal{L}_{DeepTICA}=- \\sum_{i} (\\lambda_i^{(tica)})^2$$"
    ]
   },
   {

mlcolvar/cvs/cv.py

@@ -4,6 +4,8 @@
 
 class BaseCV:
     """
+    Base collective variable class.
+    
     To inherit from this class, the class must define a BLOCKS class attribute.
     """
 

mlcolvar/utils/fes.py

@@ -302,15 +302,16 @@ def test_compute_fes():
 
     Y = np.random.rand(2, 100)
 
-    fes, bins, bounds, error_ = compute_fes(
-        X=[Y[0], Y[1]],
-        weights=np.ones_like(X),
-        bandwidth=0.02,
-        kbt=1,
-        num_samples=120,
-        bounds=None,
-        fes_to_zero=None,
-        scale_by="std",
-        blocks=2,
-        backend="sklearn",
-    )
+    if SKLEARN_IS_INSTALLED: # TODO: change to use pytest functionalities?
+        fes, bins, bounds, error_ = compute_fes(
+            X=[Y[0], Y[1]],
+            weights=np.ones_like(X),
+            bandwidth=0.02,
+            kbt=1,
+            num_samples=120,
+            bounds=None,
+            fes_to_zero=None,
+            scale_by="std",
+            blocks=2,
+            backend="sklearn",
+        )