### Setup Hook Example

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Demonstrates the use of the setup hook to dynamically build models or adjust them at the beginning of training, validation, testing, or prediction stages.

```default
class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)
```

--------------------------------

### Setup Colab Environment

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/intro_2_data.ipynb

Installs necessary packages and sets up the environment for running the tutorial in Google Colab.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print('Done!')
```

--------------------------------

### Prepare Data Example

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.RegressionCV.md

Use prepare_data to download and prepare data. This method is called in a single process to avoid data corruption in distributed settings. Avoid setting model state here; use setup() instead.

```python
# DEFAULT
# called once per node on LOCAL_RANK=0
class LitDataModule(LightningDataModule):
    def __init__(self):
        super().__init__()
        self.prepare_data_per_node = True
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/cvs_Autoencoder.ipynb

Imports necessary packages for the tutorial and includes a setup script for Google Colab environments. Ensure PyTorch, Lightning, and NumPy are installed.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
    
# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# IMPORT HELPER FUNCTIONS
from mlcolvar.utils.plot import muller_brown_potential, plot_isolines_2D, plot_metrics
```

--------------------------------

### Colab Setup Script

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/intro_3_loss_optim.ipynb

This script is used to set up the Colab environment for the tutorial. It downloads and executes a setup script.

```python
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print('Done!')
```

--------------------------------

### Install documentation dependencies

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/README.md

Install the required packages for building documentation from the repository root.

```bash
python -m pip install -e ".[doc]"
```

--------------------------------

### Setup and Teardown Callbacks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.utils.trainer.MetricsCallback.md

Callbacks for setting up and tearing down the environment.

```APIDOC
## setup

### Description
Called when fit, validate, test, predict, or tune begins. This is a good place to initialize resources.

### Method
Callback Hook

### Endpoint
N/A

### Parameters
- **trainer** (Trainer) - Description of the trainer object.
- **pl_module** (LightningModule) - Description of the LightningModule.
- **stage** (str) - The current stage (e.g., 'fit', 'validate').

### Response
N/A
```

```APIDOC
## teardown

### Description
Called when fit, validate, test, predict, or tune ends. This is a good place to release resources.

### Method
Callback Hook

### Endpoint
N/A

### Parameters
- **trainer** (Trainer) - Description of the trainer object.
- **pl_module** (LightningModule) - Description of the LightningModule.
- **stage** (str) - The current stage (e.g., 'fit', 'validate').

### Response
N/A
```

--------------------------------

### Install documentation dependencies

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/contributing.md

Install required packages to build the project documentation locally.

```bash
pip install furo nbsphinx sphinx-copybutton
```

```bash
pip install mlcolvar[doc]
```

--------------------------------

### Colab Setup Script

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/adv_newcv_scratch.ipynb

This script is used for setting up the Colab environment. It downloads and executes a setup script tailored for tutorials.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
```

--------------------------------

### Install mlcolvar from source

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/installation.md

Install the package from the local source directory.

```bash
# Activate here your Python virtual environment (e.g., with venv or conda).
cd mlcolvar
pip install .
```

--------------------------------

### Install pytest

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/contributing.md

Install the pytest framework for running automated tests.

```bash
pip install pytest
```

--------------------------------

### Setup and Data Loading

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/utils_fes.ipynb

Initializes the environment and loads collective variables from a COLVAR file.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))


from mlcolvar.utils.plot import paletteFessa
from mlcolvar.utils.io import load_dataframe
from mlcolvar.utils.fes import compute_fes, compute_deltaG
import matplotlib.pyplot as plt
from matplotlib import patches
import numpy as np

# Load COLVAR file containing collective variables (and bias information)
colvar = load_dataframe('https://raw.githubusercontent.com/EnricoTrizio/TargetedDiscriminantAnalysisCVs/refs/heads/main/alanine/deepTDA_enhanced_sampling/colvar')


# In general, you should use the simulations parameters, for example:
temperature = 300 
kb = 0.0083144621       # Boltzmann constant in kJ/(mol·K)
kbt = kb * temperature
```

--------------------------------

### Setup Environment and Import Packages

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_position-less_committor.ipynb

Configures the environment for Google Colab and imports necessary libraries for the tutorial.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# Set seed for reproducibility
torch.manual_seed(42)
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_TPI-DeepTDA.ipynb

Sets up the Colab environment by downloading and executing a setup script if running in Google Colab. Imports necessary libraries like torch, lightning, numpy, and matplotlib. Sets a manual seed for PyTorch for reproducible results.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXAMPLE', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# Set seed for reproducibility
torch.manual_seed(42)
```

--------------------------------

### setup

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.RegressionCV.md

Lifecycle hook called at the beginning of fit, validate, test, or predict stages.

```APIDOC
## setup(stage=None)

### Description
Called at the beginning of fit (train + validate), validate, test, or predict. This is a good hook when you need to build models dynamically or adjust something about them.

### Parameters
#### Request Body
- **stage** (str) - Optional - Either 'fit', 'validate', 'test', or 'predict'.
```

--------------------------------

### on_test_start

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Called at the very beginning of the testing process. Use for initial setup before any tests are run.

```APIDOC
## on_test_start() -> None

### Description
Called at the beginning of testing.
```

--------------------------------

### Initialize environment and import packages

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/adv_multitask.ipynb

Setup script for Google Colab environments and necessary library imports for mlcolvar.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
     
# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# IMPORT HELPER FUNCTIONS
from mlcolvar.cvs import MultiTaskCV, AutoEncoderCV
from mlcolvar.core.loss import TDALoss
from mlcolvar.core.transform.utils import Statistics
from mlcolvar.utils.plot import muller_brown_potential, plot_isolines_2D, plot_metrics
from mlcolvar.utils.trainer import MetricsCallback

# Set seed for reproducibility
torch.manual_seed(42)
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_stateinterpreter.ipynb

Sets up the environment for Google Colab by downloading and executing a setup script if running in Colab. Imports essential libraries for PyTorch, Lightning, NumPy, Matplotlib, and mlcolvar utilities. Sets a manual seed for reproducibility.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXAMPLE', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt
import mlcolvar.utils.plot

# Set seed for reproducibility
torch.manual_seed(1)
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_committor.ipynb

Sets up the Colab environment if running in Google Colab by downloading and executing a setup script. It then imports necessary libraries for PyTorch, Lightning, NumPy, and Matplotlib.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

def convert_model(model_name, n_input):
    loaded_model = torch.jit.load(model_name).to(torch.device('cpu')).to(torch.float32)
    fake_input = torch.rand(n_input).to(torch.float32)
    loaded_model(fake_input)
    frozen_model = torch.jit.trace(loaded_model, fake_input)
    torch.jit.save(frozen_model, model_name)

# Set seed for reproducibility
torch.manual_seed(42)
torch.set_default_dtype(torch.float64)

```

--------------------------------

### Colab Setup Script

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/paper_experiments/paper_4_multitask.ipynb

This script handles the setup for Google Colab, including downloading and executing a setup script for the MLColvar environment. It checks if the script is running in Colab and proceeds with the setup if it is.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXPERIMENT', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
```

--------------------------------

### Install mlcolvar from GitHub

Source: https://github.com/luigibonati/mlcolvar/blob/main/README.md

Developer-focused installation method allowing for editable source code modifications.

```bash
git clone https://github.com/luigibonati/mlcolvar.git
cd mlcolvar
pip -e install .
```

--------------------------------

### Colab Setup Script for mlcolvar

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/adv_preprocessing.ipynb

This Python code sets up the environment for running mlcolvar tutorials in Google Colab. It downloads and executes a setup script, printing its output.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
     
import torch
import mlcolvar
import numpy as np
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_DeepTICA.ipynb

This code block handles the setup for Google Colab environments by downloading and executing a setup script if detected. It then imports essential Python libraries for deep learning, scientific computing, and plotting, and sets a manual seed for reproducible results.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXAMPLE', shell=True, stdout=subprocess.PIPE)
    print('Done!')

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# Set seed for reproducibility
torch.manual_seed(42)
```

--------------------------------

### Environment and Package Setup

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/paper_experiments/paper_3_timelagged.ipynb

Initializes the environment for Google Colab and imports necessary libraries for data processing and model training.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXPERIMENT', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
    
# IMPORT PACKAGES
import torch
import lightning as pl
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
import numpy as np
import pandas as pd
import matplotlib as mlp
import matplotlib.pyplot as plt
import subprocess

# IMPORT from MLCVS 
from mlcolvar.data import DictModule
from mlcolvar.core.transform import Normalization
from mlcolvar.core.transform.utils import Statistics
from mlcolvar.utils.fes import compute_fes
from mlcolvar.utils.io import create_dataset_from_files, load_dataframe
from mlcolvar.utils.plot import muller_brown_potential_three_states, plot_isolines_2D, plot_metrics, paletteFessa
from mlcolvar.utils.trainer import MetricsCallback


# IMPORT utils functions fo input generation
from utils.generate_input import gen_input_md,gen_input_md_potential,gen_plumed_tica

# Set seed for reproducibility
torch.manual_seed(42)

# ============================ SIMULATIONS VARIABLES ================================
run_calculations = False

if run_calculations:
    # plumed setup
    PLUMED_SOURCE = '/home/etrizio@iit.local/Bin/dev/plumed2-dev/sourceme.sh'
    PLUMED_EXE = f'source {PLUMED_SOURCE} && plumed'
    PLUMED_VES_MD = f"{PLUMED_EXE} ves_md_linearexpansion < input_md.dat"

    #test plumed
    subprocess.run(f"{PLUMED_EXE}", shell=True, executable='/bin/bash')
```

--------------------------------

### Initialize and setup DictModule

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.data.DictModule.md

Create a DictModule from a DictDataset and prepare data loaders for training.

```pycon
>>> x = torch.randn((50, 2))
>>> dataset = DictDataset({'data': x, 'labels': x.square().sum(dim=1)})
>>> datamodule = DictModule(dataset, lengths=[0.75,0.2,0.05], batch_size=25)
```

```pycon
>>> # This is usually called by PyTorch Lightning.
>>> datamodule.setup()
>>> train_loader = datamodule.train_dataloader()
>>> for batch in train_loader:
...     batch_x = batch['data']
...     batch_y = batch['labels']
...     print(batch_x.shape, batch_y.shape)
torch.Size([25, 2]) torch.Size([25])
torch.Size([13, 2]) torch.Size([13])
```

```pycon
>>> val_loader = datamodule.val_dataloader()
>>> test_loader = datamodule.test_dataloader()
```

--------------------------------

### Setup Environment and Import Packages

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/cvs_DeepTICA.ipynb

Configures the environment for Google Colab and imports necessary libraries for data processing and visualization.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))
    
# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# IMPORT HELPER FUNCTIONS
from mlcolvar.utils.plot import muller_brown_potential, plot_isolines_2D, plot_metrics

# Set seed for reproducibility
torch.manual_seed(42)
```

--------------------------------

### setup

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.VariationalAutoEncoderCV.md

Called at the beginning of fit, validate, test, or predict stages. Useful for dynamic model building or adjustments.

```APIDOC
## setup(stage=None)

### Description
Called at the beginning of fit (train + validate), validate, test, or predict. This is a good hook when you need to build models dynamically or adjust something about them. This hook is called on every process when using DDP.

### Parameters
#### Path Parameters
None

#### Query Parameters
- **stage** (str) - either `'fit'`, `'validate'`, `'test'`, or `'predict'`

### Request Example
```python
import torch.nn as nn

class LitModel(object):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        # download_data()
        # tokenize()
        pass

    def setup(self, stage):
        # data = load_data(...)
        # self.l1 = nn.Linear(28, data.num_classes)
        pass
```

### Response
None

### Response Example
None
```

--------------------------------

### on_train_start

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Called at the beginning of the training process, after the initial sanity check. Use for setup before the main training loop begins.

```APIDOC
## on_train_start() -> None

### Description
Called at the beginning of training after sanity check.
```

--------------------------------

### Example of prepare_data method

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Demonstrates the correct usage of the prepare_data method for downloading and preparing data. Avoid setting model state directly within this method.

```python
def prepare_data(self):
    # good
    download_data()
    tokenize()
    etc()

    # bad
    self.split = data_split
    self.some_state = some_other_state()
```

--------------------------------

### PairwiseDistances Setup Method

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.transform.descriptors.PairwiseDistances.md

Initializes parameters based on a PyTorch Lightning datamodule.

```APIDOC
## setup_from_datamodule

### Description
Initialize parameters based on pytorch lighting datamodule.

### Method
setup_from_datamodule

### Parameters
#### Path Parameters
- **datamodule** - Required - The PyTorch Lightning datamodule

### Attributes
(No specific attributes mentioned in the provided text for this method)
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_DeepLDA.ipynb

This snippet handles environment setup for Google Colab and imports necessary Python libraries for data analysis and machine learning. It includes a check to run setup scripts only in a Colab environment.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXAMPLE', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# Set seed for reproducibility
torch.manual_seed(41)
```

--------------------------------

### Install and run black formatter

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/contributing.md

Install the black linter and use it to format Python files or Jupyter notebooks.

```bash
pip install black
```

```bash
pip install black[jupyter]
```

```bash
black your_file
```

--------------------------------

### Environment Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/cvs_DeepLDA.ipynb

Initializes the environment for Google Colab and imports necessary libraries for Deep-LDA implementation.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh TUTORIAL', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning
import numpy as np
import matplotlib.pyplot as plt

# IMPORT HELPER FUNCTIONS
from mlcolvar.utils.plot import muller_brown_potential, plot_isolines_2D, plot_metrics
```

--------------------------------

### on_predict_start

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Called at the very beginning of the prediction process. Use for initial setup before any predictions are made.

```APIDOC
## on_predict_start() -> None

### Description
Called at the beginning of predicting.
```

--------------------------------

### Setup Lightning Trainer Callbacks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/intro_1_training.ipynb

Configures callbacks for metrics tracking and early stopping during the training process.

```python
from lightning import Trainer
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
from mlcolvar.utils.trainer import MetricsCallback

# define callbacks
metrics = MetricsCallback()
early_stopping = EarlyStopping(monitor="valid_loss", patience=10, min_delta=1e-5)
```

--------------------------------

### Setup PyTorch Lightning Trainer and Callbacks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/cvs_DeepTDA.ipynb

Defines and configures callbacks for training, such as metrics tracking and early stopping, and initializes the PyTorch Lightning Trainer.

```python
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
from mlcolvar.utils.trainer import MetricsCallback

# define callbacks
metrics = MetricsCallback()
early_stopping = EarlyStopping(monitor="train_loss", mode='min', min_delta=1e-1, patience=20)

# define trainer
trainer = lightning.Trainer(callbacks=[metrics, early_stopping],
                     max_epochs=500, logger=None, enable_checkpointing=False)
```

--------------------------------

### Setup simulation input files for PLUMED

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/data/muller-brown/run-md-plumed.ipynb

Creates necessary input files (`md_potential`, `md_input`, `plumed.dat`) for a PLUMED simulation using the `ves_md_linearexpansion` driver. Ensure the `MULLER_BROWN_FORMULA` is defined.

```python
folder = 'unbiased/state-0/'

Path(folder).mkdir(parents=True, exist_ok=True)

# md_potential for ves_md_linearexpansion (actual potential is in plumed.dat)
with open(folder+"md_potential","w") as f:
    print("""#! FIELDS idx_dim1 idx_dim2 pot.coeffs index description
#! SET type LinearBasisSet
#! SET ndimensions  2
#! SET ncoeffs_total 9 
#! SET shape_dim1  3
#! SET shape_dim2  3
       0       0         0.0000000000000000e+00       0  1*1
#!-------------------
""",file=f)

# md_input for ves_md_linearexpansion
with open(folder+"md_input","w") as f:
    print("""
nstep                   400000
tstep                   0.005
temperature             1.
friction                10.0
random_seed             1  
plumed_input            plumed.dat
dimension               2
replicas                1
basis_functions_1       BF_POWERS ORDER=2 MINIMUM=-4.0 MAXIMUM=+4.0
basis_functions_2       BF_POWERS ORDER=2 MINIMUM=-4.0 MAXIMUM=+4.0
input_coeffs            md_potential
initial_position        -0.25,1.75
output_potential        out_potential.data
output_potential_grid   100
output_histogram        histogram.data
""",file=f)

with open(folder+"plumed.dat","w") as f:
    print(f"# vim:ft=plumed
UNITS NATURAL
p: POSITION ATOM=1
ene: CUSTOM ARG=p.x,p.y PERIODIC=NO FUNC={MULLER_BROWN_FORMULA}
pot: BIASVALUE ARG=ene

lwall: LOWER_WALLS ARG=p.x KAPPA=1000 AT=-1.3
uwall: UPPER_WALLS ARG=p.x KAPPA=1000 AT=+1.0

PRINT STRIDE=200 ARG=* FILE=COLVAR
",file=f)

clean(folder)
subprocess.run(f"{PLUMED_EXE} ves_md_linearexpansion < md_input", cwd=folder, shell=True)
```

--------------------------------

### PLUMED Configuration File

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/intro_1_training.ipynb

Example configuration for evaluating a PyTorch model within the PLUMED framework.

```text
# ------------- plumed.dat -------------
p:  POSITION ATOM=1
cv: PYTORCH_MODEL FILE=model.ptc ARG=p.x,p.y

PRINT STRIDE=100 ARG=cv.*
# --------------------------------------
```

--------------------------------

### setup(stage=None)

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.AutoEncoderCV.md

Called at the beginning of fit, validate, test, or predict. Useful for dynamic model building or adjustments. This hook is called on every process when using DDP.

```APIDOC
## setup(stage=None)

### Description
Called at the beginning of fit (train + validate), validate, test, or predict. This is a good hook when you need to build models dynamically or adjust something about them. This hook is called on every process when using DDP.

### Args
- **stage** (string) - Optional - either `'fit'`, `'validate'`, `'test'`, or `'predict'`

### Example
```python
class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)
```
```

--------------------------------

### setup

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Called at the beginning of fit, validate, test, or predict stages. This hook is useful for dynamically building models or adjusting them based on the current stage.

```APIDOC
## setup(stage: str) -> None

### Description
Called at the beginning of fit (train + validate), validate, test, or predict. This is a good hook when you need to build models dynamically or adjust something about them. This hook is called on every process when using DDP.

### Parameters
#### Arguments
- **stage**: either `'fit'`, `'validate'`, `'test'`, or `'predict'`

### Example
```default
class LitModel(...):
    def __init__(self):
        self.l1 = None

    def prepare_data(self):
        download_data()
        tokenize()

        # don't do this
        self.something = else

    def setup(self, stage):
        data = load_data(...)
        self.l1 = nn.Linear(28, data.num_classes)
```
```

--------------------------------

### Install mlcolvar via pip

Source: https://github.com/luigibonati/mlcolvar/blob/main/README.md

Standard installation method for users to get the library and its dependencies.

```bash
pip install mlcolvar
```

--------------------------------

### Colab Setup and Package Imports

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/paper_experiments/paper_2_supervised.ipynb

Sets up the Colab environment if running in Google Colab and imports necessary Python packages for machine learning, data handling, and plotting.

```python
# Colab setup
import os

if os.getenv("COLAB_RELEASE_TAG"):
    import subprocess
    subprocess.run('wget https://raw.githubusercontent.com/luigibonati/mlcolvar/main/colab_setup.sh', shell=True)
    cmd = subprocess.run('bash colab_setup.sh EXPERIMENT', shell=True, stdout=subprocess.PIPE)
    print(cmd.stdout.decode('utf-8'))

# IMPORT PACKAGES
import torch
import lightning as pl
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
import numpy as np
import pandas as pd
import matplotlib as mlp
import matplotlib.pyplot as plt
import subprocess

# IMPORT from MLCVS 
from mlcolvar.data import DictModule
from mlcolvar.core.transform import Normalization
from mlcolvar.core.transform.utils import Statistics
from mlcolvar.utils.fes import compute_fes
from mlcolvar.utils.io import create_dataset_from_files, load_dataframe
from mlcolvar.utils.plot import muller_brown_potential_three_states, plot_isolines_2D, plot_metrics, paletteFessa
from mlcolvar.utils.trainer import MetricsCallback


# IMPORT utils functions fo input generation
from utils.generate_input import gen_input_md,gen_input_md_potential,gen_plumed 

# Set seed for reproducibility
torch.manual_seed(42)

# ============================ SIMULATIONS VARIABLES ================================
run_calculations = False

if run_calculations:
    # plumed setup
    PLUMED_SOURCE = '/home/etrizio@iit.local/Bin/dev/plumed2-dev/sourceme.sh'
    PLUMED_EXE = f'source {PLUMED_SOURCE} && plumed'
    PLUMED_VES_MD = f"{PLUMED_EXE} ves_md_linearexpansion < input_md.dat"

    #test plumed
    subprocess.run(f"{PLUMED_EXE}", shell=True, executable='/bin/bash')
```

--------------------------------

### Method: setup_from_datamodule

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.transform.descriptors.CoordinationNumbers.md

Initializes parameters based on a pytorch lighting datamodule.

```APIDOC
## setup_from_datamodule(datamodule)

### Description
Initialize parameters based on pytorch lighting datamodule.
```

--------------------------------

### Validate mlcolvar installation

Source: https://github.com/luigibonati/mlcolvar/blob/main/README.md

Install test dependencies and run the test suite to verify the installation.

```bash
pip install mlcolvar[test]
pytest --pyargs mlcolvar.tests
```

--------------------------------

### Build documentation

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/contributing.md

Generate HTML documentation from the source files.

```bash
cd docs/
make html
```

--------------------------------

### Install mlcolvar Locally

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/contributing.md

Install the package in editable mode after activating your virtual environment. This ensures your local changes are reflected in the installed package.

```bash
# Activate here your Python virtual environment (e.g., with venv or conda).
cd mlcolvar
pip install -e .
```

--------------------------------

### Install Additional Packages for Docs and Tests

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/contributing.md

Install extra packages required for running regtests and building documentation. This command installs mlcolvar with the 'docs' and 'test' extras.

```bash
pip install mlcolvar[docs,test]
```

--------------------------------

### Install mlcolvar in editable mode

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/installation.md

Install the package in editable mode for development purposes.

```bash
pip install -e .
```

--------------------------------

### Configure and Run Lightning Trainer

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_DeepLDA.ipynb

Set up early stopping and metrics callbacks, then fit the model using the Lightning Trainer.

```python
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
from mlcolvar.utils.trainer import MetricsCallback

# define callbacks
metrics = MetricsCallback()
early_stopping = EarlyStopping(monitor="valid_loss", min_delta=0.1, patience=50)

# define trainer
trainer = lightning.Trainer(callbacks=[metrics, early_stopping],
                     max_epochs=None, logger=None, enable_checkpointing=False)

# fit
trainer.fit( model, datamodule )
```

--------------------------------

### Install mlcolvar via pip

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/installation.md

Install the package using pip within an activated virtual environment.

```bash
# Activate here your Python virtual environment (e.g., with venv or conda).
pip install mlcolvar
```

--------------------------------

### SwitchingFunctions setup_from_datamodule Method

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.transform.tools.SwitchingFunctions.md

Initializes parameters based on a PyTorch Lightning datamodule.

```APIDOC
## setup_from_datamodule Method

### Description
Initialize parameters based on pytorch lighting datamodule.

### Method
setup_from_datamodule

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "datamodule": "datamodule"
}
```

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Initialize directory and potential

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/data/muller-brown-3states/run-md-plumed.ipynb

Creates a target directory and initializes the md_potential file.

```python
folder = 'unbiased/state-2/'

Path(folder).mkdir(parents=True, exist_ok=True)

# md_potential for ves_md_linearexpansion (actual potential is in plumed.dat)
with open(folder+"md_potential","w") as f:
    print("""#! FIELDS idx_dim1 idx_dim2 pot.coeffs index description
#! SET type LinearBasisSet
#! SET ndimensions  2
#! SET ncoeffs_total 9 
#! SET shape_dim1  3
#! SET shape_dim2  3
       0       0         0.0000000000000000e+00       0  1*1
#!-------------------
""",file=f)
```

--------------------------------

### Initialize Lightning Trainer and Callbacks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/cvs_DeepTDA.ipynb

Sets up the `lightning.Trainer` with `MetricsCallback` and `EarlyStopping` callbacks. The trainer is configured for a maximum of 400 epochs and disables logging and checkpointing.

```python
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
from mlcolvar.utils.trainer import MetricsCallback

# define callbacks
metrics = MetricsCallback()
early_stopping = EarlyStopping(monitor="valid_loss", mode='min', min_delta=1e-2, patience=20)

# define trainer
trainer = lightning.Trainer(callbacks=[metrics, early_stopping],
                     max_epochs=400, logger=None, enable_checkpointing=False)
```

--------------------------------

### Configure Trainer and Callbacks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/expl_features_relevances.ipynb

Sets up the Lightning trainer with early stopping and custom metrics tracking for model training.

```python
from lightning.pytorch.callbacks.early_stopping import EarlyStopping
from mlcolvar.utils.trainer import MetricsCallback

# define callbacks
metrics = MetricsCallback()
early_stopping = EarlyStopping(monitor="valid_loss", min_delta=0.1, patience=50)

# define trainer
trainer = lightning.Trainer(callbacks=[metrics, early_stopping],
                     max_epochs=None, logger=None, enable_checkpointing=False)
```

--------------------------------

### DataModule Lifecycle Hooks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.DeepLDA.md

Lifecycle hooks for managing data preparation and model setup.

```APIDOC
## setup

### Description
Hook called at the beginning of fit, validate, test, or predict stages. Used for dynamic model building.

### Parameters
- **stage** (str) - Optional - The current stage: 'fit', 'validate', 'test', or 'predict'.

## teardown

### Description
Hook called at the end of fit, validate, test, or predict stages.

### Parameters
- **stage** (str) - Required - The stage that just finished: 'fit', 'validate', 'test', or 'predict'.
```

--------------------------------

### Transform Setup from Datamodule

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.transform.Transform.md

Initializes transform parameters based on a PyTorch Lightning datamodule.

```APIDOC
## setup_from_datamodule(datamodule)

### Description
Initialize parameters based on pytorch lighting datamodule.

### Attributes
(Details about attributes would be listed here if provided in the source)
```

--------------------------------

### Simulation output logs

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/data/muller-brown-3states/run-md-plumed.ipynb

Example console output from the cleanup process and simulation execution.

```text
rm: cannot remove 'KERNELS': No such file or directory
rm: cannot remove 'bck.*': No such file or directory
rm: cannot remove 'out*': No such file or directory
rm: cannot remove 'histogram*': No such file or directory
rm: cannot remove 'potential-coeffs.out.data': No such file or directory
rm: cannot remove 'stats.out': No such file or directory
No protocol specified
```

```text
Replicas                              1
Cores per replica                     1
Number of steps                       400000
Timestep                              0.005000
Temperature                           1.000000
Friction                              10.000000
Random seed                           -1
Dimensions                            2
Basis Function 1                      BF_POWERS ORDER=2 MINIMUM=-4.0 MAXIMUM=+4.0
Basis Function 2                      BF_POWERS ORDER=2 MINIMUM=-4.0 MAXIMUM=+4.0
PLUMED input                          plumed.dat
kBoltzmann taken as 1, use NATURAL_UNITS in the plumed input
```

```text
CompletedProcess(args='plumed ves_md_linearexpansion < md_input', returncode=0)
```

--------------------------------

### Configure and Fit Trainer

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/adv_infinitesimal_generator.ipynb

Sets up the Lightning trainer with metrics callbacks and executes the model fitting process.

```python
# define callbacks
from mlcolvar.utils.trainer import MetricsCallback

metrics = MetricsCallback()

 # you can use a small number of epochs for testing in the range of 15/20k epochs
trainer = lightning.Trainer(callbacks=[metrics],
                            max_epochs=5, 
                            num_sanity_val_steps=0,
                            limit_val_batches=0,
                            enable_checkpointing=False,
                            enable_progress_bar = True, # disable the progress bar
                            logger=None
                            )
# fit model
trainer.fit(model, datamodule)
```

--------------------------------

### ContinuousHistogram Methods

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.transform.tools.ContinuousHistogram.md

Methods available for the ContinuousHistogram class, including forward pass and datamodule setup.

```APIDOC
## forward(x: Tensor)

### Description
Define the computation performed at every call. Note: Call the Module instance instead of this method to ensure registered hooks are executed.

## setup_from_datamodule(datamodule)

### Description
Initialize parameters based on pytorch lighting datamodule.
```

--------------------------------

### Create Dataset from Files

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_TPI-DeepTDA.ipynb

Initializes the dataset and data module for training. Adjust 'stop' and 'stride' parameters to control the amount of data used.

```python
dataset, df = create_dataset_from_files(filenames,
                                        create_labels=True,
                                        return_dataframe=True,
                                        filter_args={'regex':'cont' }, # select distances between heavy atoms
                                        stop=10000,
                                        stride=2)

datamodule = DictModule(dataset,lengths=[0.8,0.2])
```

--------------------------------

### on_validation_model_eval

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Hook called when the validation loop starts, typically to set the model to evaluation mode.

```APIDOC
## on_validation_model_eval

### Description
Called when the validation loop starts. The validation loop by default calls `.eval()` on the LightningModule before it starts. Override this hook to change the behavior. See also `on_validation_model_train()`.

### Method Signature
`on_validation_model_eval() -> None`
```

--------------------------------

### Compile documentation to HTML

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/README.md

Generate static HTML documentation files using the Makefile.

```bash
make html
```

--------------------------------

### Initialize System Constants

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/examples/ex_position-less_committor.ipynb

Sets the temperature and calculates the Boltzmann factor for the system.

```python
# temperature in Kelvin
T = 300 

# Boltzmann factor in the RIGHT ENERGY UNITS!
kb = 0.0083144621 # kJ/mol
beta = 1/(kb*T)
print(f'Beta: {beta} \n1/beta: {1/beta}')
```

--------------------------------

### Initialize State-1 Directory

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/data/muller-brown-3states/run-md-plumed.ipynb

Creates the directory for the second state in the simulation.

```python
folder = 'unbiased/state-1/'

Path(folder).mkdir(parents=True, exist_ok=True)
```

--------------------------------

### Data Lifecycle Hooks

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.DeepTDA.md

Methods for managing data preparation and model setup within the Lightning framework.

```APIDOC
## prepare_data()

### Description
Downloads and prepares data. This method is called only within a single process to prevent data corruption in distributed settings.

### Parameters
- **prepare_data_per_node** (bool) - Optional - If True, called once per node on LOCAL_RANK=0. If False, called once in total on GLOBAL_RANK=0.

## setup(stage=None)

### Description
Hook called at the beginning of fit, validate, test, or predict stages. Used for dynamic model building or adjustments.

### Parameters
- **stage** (str) - Optional - The current stage: 'fit', 'validate', 'test', or 'predict'.
```

--------------------------------

### on_test_batch_start

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.core.nn.FeedForward.md

Called in the test loop before a batch is processed. Allows for custom logic or setup before handling each test batch.

```APIDOC
## on_test_batch_start(batch: Any, batch_idx: int, dataloader_idx: int = 0) -> None

### Description
Called in the test loop before anything happens for that batch.

### Parameters
#### Path Parameters
- **batch** (Any) - The batched data as it is returned by the test DataLoader.
- **batch_idx** (int) - The index of the batch.
- **dataloader_idx** (int) - The index of the dataloader. Defaults to 0.
```

--------------------------------

### Simulation Configuration Summary

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/data/muller-brown/run-md-plumed.ipynb

This output summarizes the simulation parameters as read from the input files. It confirms settings like number of replicas, timestep, temperature, and basis functions.

```text
Replicas                              1
Cores per replica                     1
Number of steps                       1000000
Timestep                              0.005000
Temperature                           2.500000
Friction                              10.000000
Random seed                           -1
Dimensions                            2
Basis Function 1                      BF_POWERS ORDER=2 MINIMUM=-4.0 MAXIMUM=+4.0
Basis Function 2                      BF_POWERS ORDER=2 MINIMUM=-4.0 MAXIMUM=+4.0
PLUMED input                          plumed.dat
kBoltzmann taken as 1, use NATURAL_UNITS in the plumed input
```

--------------------------------

### Import Lightning Framework

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/intro_3_loss_optim.ipynb

Import the lightning library to enable framework-specific features like GPU acceleration.

```python
import lightning
```

--------------------------------

### Save Single Argument Hyperparameters

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/autosummary/mlcolvar.cvs.RegressionCV.md

Example of saving a single Namespace object containing hyperparameters to the hparams attribute.

```python
from lightning.pytorch.core.mixins import HyperparametersMixin
class SingleArgModel(HyperparametersMixin):
    def __init__(self, params):
        super().__init__()
        # manually assign single argument
        self.save_hyperparameters(params)
    def forward(self, *args, **kwargs):
        ...
```

--------------------------------

### Initialize simulation folder

Source: https://github.com/luigibonati/mlcolvar/blob/main/docs/notebooks/tutorials/data/muller-brown/run-md-plumed.ipynb

Creates a directory for simulation state 1. This is typically part of a larger workflow setting up multiple simulation states.

```python
folder = 'unbiased/state-1/'

Path(folder).mkdir(parents=True, exist_ok=True)

```