From 1590bfba7cbbfbd999ad3d9954e2f7f049fca760 Mon Sep 17 00:00:00 2001 From: Luigi Bonati Date: Wed, 25 Oct 2023 01:04:58 +0200 Subject: [PATCH 1/5] [docs] fix equation style deeptica notebook --- docs/notebooks/tutorials/cvs_DeepTICA.ipynb | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/notebooks/tutorials/cvs_DeepTICA.ipynb b/docs/notebooks/tutorials/cvs_DeepTICA.ipynb index b645386b..baccc804 100644 --- a/docs/notebooks/tutorials/cvs_DeepTICA.ipynb +++ b/docs/notebooks/tutorials/cvs_DeepTICA.ipynb @@ -40,13 +40,9 @@ "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", @@ -54,9 +50,7 @@ "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$$" ] }, { From ea107e28b631a2103c8b41b75bd70eac62ef6cc2 Mon Sep 17 00:00:00 2001 From: Luigi Bonati Date: Wed, 25 Oct 2023 01:05:19 +0200 Subject: [PATCH 2/5] [docs] add optional install instructions to contributing --- docs/contributing.rst | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 52857621..23708275 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -24,6 +24,12 @@ implementation path from the start. Then cd mlcolvar pip install -e . +In order to perform the regtests you can install the required packages with: + +.. code-block:: bash + + pip install mlcolvar[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 From 4e5a2ba5e89a102c2cef4f7556d7ee166253c76b Mon Sep 17 00:00:00 2001 From: Luigi Bonati Date: Wed, 25 Oct 2023 01:06:43 +0200 Subject: [PATCH 3/5] [docs] changed docstring basecv --- docs/autosummary/mlcolvar.cvs.BaseCV.rst | 46 ++++++++++++++++++++++++ mlcolvar/cvs/cv.py | 2 ++ 2 files changed, 48 insertions(+) create mode 100644 docs/autosummary/mlcolvar.cvs.BaseCV.rst diff --git a/docs/autosummary/mlcolvar.cvs.BaseCV.rst b/docs/autosummary/mlcolvar.cvs.BaseCV.rst new file mode 100644 index 00000000..33fa73c0 --- /dev/null +++ b/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 + + + + \ No newline at end of file diff --git a/mlcolvar/cvs/cv.py b/mlcolvar/cvs/cv.py index 05e2681a..6d4b9b36 100644 --- a/mlcolvar/cvs/cv.py +++ b/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. """ From cfe811442b905069924702efd14f0f3c6cc13ed6 Mon Sep 17 00:00:00 2001 From: Luigi Bonati Date: Wed, 25 Oct 2023 01:43:16 +0200 Subject: [PATCH 4/5] [tests] fix test w/scikit-learn for plot fes --- mlcolvar/utils/fes.py | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/mlcolvar/utils/fes.py b/mlcolvar/utils/fes.py index 86bdb990..ce8aaba8 100644 --- a/mlcolvar/utils/fes.py +++ b/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", + ) From ba2b97b6216af19d4af85248f711cbcd3deb09f6 Mon Sep 17 00:00:00 2001 From: Luigi Bonati Date: Wed, 25 Oct 2023 01:51:49 +0200 Subject: [PATCH 5/5] [docs] add instructions to install and execute pytest --- docs/contributing.rst | 6 +++--- docs/installation.rst | 7 +++++++ 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 23708275..550f4981 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -24,11 +24,11 @@ implementation path from the start. Then cd mlcolvar pip install -e . -In order to perform the regtests you can install the required packages with: +4. In order to perform the regtests and build the documentation you need to install additional packages: -.. code-block:: bash + .. code-block:: bash - pip install mlcolvar[test] + pip install mlcolvar[docs,test] Once your environment is set up you are ready to implement your changes. diff --git a/docs/installation.rst b/docs/installation.rst index 48ef9f14..ce7bcd22 100644 --- a/docs/installation.rst +++ b/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 ----------------------------