pymbar

https://pymbar.readthedocs.io/en/stable
Admin
pymbar is a Python implementation of the multistate Bennett acceptance ratio (MBAR) method for...
Tokens:35,740
Snippets:182
Trust Score:8.3
Update:8 months ago
Show doc for...
Tokens:
Raw
### Install PyMBAR using Pip

Source: https://pymbar.readthedocs.io/en/stable/_sources/getting_started.rst

Installs the PyMBAR package from the Python Package Index (PyPI) using pip. This is an alternative installation method.

```bash
$ pip install pymbar
```

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

### Install pymbar using Pip

Source: https://pymbar.readthedocs.io/en/stable/getting_started

Installs the pymbar library from the Python Package Index (PyPI) using pip. This is an alternative installation method.

```bash
$ pip install pymbar

```

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

### Install pymbar using Conda

Source: https://pymbar.readthedocs.io/en/stable/getting_started

Installs the pymbar library using the conda package manager from the conda-forge channel. This is the recommended method for installation.

```bash
$ conda install -c conda-forge pymbar

```

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

### Custom Solver Protocol Example with Options - Python

Source: https://pymbar.readthedocs.io/en/stable/strategies_for_solution

Illustrates creating a custom solver protocol with specific options and tolerances for different optimization methods. This example shows how to pass parameters like 'tol', 'continuation', and 'options' to scip.optimize methods.

```python
solver_protocol = (
        dict(method="hybr"),
        dict(method="L-BFGS-B", tol = 1.0e-5, continuation = True, options=dict(maxiter=1000)),
        dict(method="adaptive", tol = 1.0e-12, options=dict(maxiter=1000,min_sc_iter=5))
)
```

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

### Install PyMBAR using Conda

Source: https://pymbar.readthedocs.io/en/stable/_sources/getting_started.rst

Installs the PyMBAR package using the conda package manager from the conda-forge channel. This is the recommended method for installation.

```bash
$ conda install -c conda-forge pymbar
```

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

### Install PyMBAR Development Version from GitHub using Pip

Source: https://pymbar.readthedocs.io/en/stable/_sources/getting_started.rst

Installs the latest development version of PyMBAR directly from its GitHub repository using pip. This is useful for testing the newest features or contributing to the project.

```bash
$ pip install git+https://github.com/choderalab/pymbar.git
```

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

### Install pymbar Development Version from GitHub

Source: https://pymbar.readthedocs.io/en/stable/getting_started

Installs the latest development version of pymbar directly from its GitHub repository using pip. This is useful for accessing the most recent features or for development purposes.

```bash
$ pip install git+https://github.com/choderalab/pymbar.git

```

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

### Install Dependencies and Run pymbar Tests with Pytest

Source: https://pymbar.readthedocs.io/en/stable/getting_started

Installs necessary testing dependencies (pytest, statsmodels) using conda and then executes the pymbar test suite using pytest. This verifies the correct installation and functionality of the library.

```bash
$ conda install pytest statsmodels
$ pytest -v pymbar

```

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

### Install Testing Dependencies using Conda

Source: https://pymbar.readthedocs.io/en/stable/_sources/getting_started.rst

Installs the necessary dependencies for running PyMBAR's tests, including pytest, statsmodels, and pytables, using the conda package manager.

```bash
$ conda install pytest statsmodels
```

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

### MBAR Initialization Example

Source: https://pymbar.readthedocs.io/en/stable/mbar

Demonstrates how to initialize the MBAR object with sampled data. It requires potential energy data (u_kn) and the number of samples per state (N_k).

```python
from pymbar import testsystems
from pymbar import MBAR

(x_n, u_kn, N_k, s_n) = testsystems.HarmonicOscillatorsTestCase().sample(mode='u_kn')
mbar = MBAR(u_kn, N_k)
```

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

### Default Solver Protocol Example in Python

Source: https://pymbar.readthedocs.io/en/stable/_sources/strategies_for_solution.rst

Demonstrates the construction of a default solver protocol using a tuple of dictionaries, where each dictionary represents an optimization operation. This protocol is designed for high accuracy in most circumstances.

```python
solver_protocol = (
       dict(method="hybr", continuation=True),
   )
```

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

### Run PyMBAR Tests using Pytest

Source: https://pymbar.readthedocs.io/en/stable/_sources/getting_started.rst

Executes the PyMBAR test suite from within the project directory using the pytest framework. The '-v' flag enables verbose output.

```bash
$ pytest -v pymbar
```

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

### Initialize MBAR and compute free energy differences (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/moving_from_pymbar3.rst

Demonstrates how to initialize the MBAR object and compute free energy differences in pymbar v3.x and the updated v4.0. The v4.0 example shows the change from tuple returns to dictionary returns for results and errors.

```python
mbar = MBAR(u_kn, N_k)
results, errors = mbar.getFreeEnergyDifferences()
print(results[0])
print(errors[0])
```

```python
mbar = MBAR(u_kn, N_k)
results = mbar.compute_free_energy_differences()
print(results['Delta_f'])
print(results['dDelta_f'])
```

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

### Get Free Energy Surface Values

Source: https://pymbar.readthedocs.io/en/stable/fes_with_pymbar

Retrieves the values of the free energy surface at specified coordinates, along with uncertainties if available.

```APIDOC
## Get Free Energy Surface Values

### Description
Retrieves the values of the free energy surface at the specified coordinates. When available, it also returns the uncertainties associated with these values.

### Method
`get_fes(_x_coords_)

### Parameters
#### Path Parameters
- **x_coords** (np.ndarray) - The coordinates at which to retrieve the free energy values.

### Request Example
```python
# Assuming 'fes_object' is a generated FES object
coordinates = [[0.1, 0.2], [0.3, 0.4]] # Example coordinates
fes_values = fes_object.get_fes(coordinates)
```

### Response
#### Success Response (200)
- **fes_values** (dict) - A dictionary containing the free energy values and their uncertainties at the specified coordinates.

#### Response Example
```json
{
  "free_energy": [0.5, 0.8],
  "uncertainty": [0.1, 0.15]
}
```
```

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

### Generate and Analyze Correlated Timeseries Data (Python)

Source: https://pymbar.readthedocs.io/en/stable/timeseries

This example demonstrates generating multiple correlated timeseries of varying lengths, estimating their statistical inefficiency, and then subsampling them to obtain uncorrelated samples. The subsampled data is then concatenated into a single timeseries.

```python
>>> # Generate multiple correlated timeseries data of different lengths.
>>> T_k = [1000, 2000, 3000, 4000, 5000]
>>> K = len(T_k) # number of timeseries
>>> tau = 5.0 # exponential relaxation time
>>> A_kt = [ testsystems.correlated_timeseries_example(N=T, tau=tau) for T in T_k ] # A_kt[k] is correlated timeseries k
>>> # Estimate statistical inefficiency from all timeseries data.
>>> g = statistical_inefficiency_multiple(A_kt)
>>> # Count number of uncorrelated samples in each timeseries.
>>> N_k = np.array([ len(subsample_correlated_data(A_t, g=g)) for A_t in A_kt ]) # N_k[k] is the number of uncorrelated samples in timeseries k
>>> N = N_k.sum() # total number of uncorrelated samples
>>> # Subsample all trajectories to produce uncorrelated samples
>>> A_kn = [ A_t[subsample_correlated_data(A_t, g=g)] for A_t in A_kt ] # A_kn[k] is uncorrelated subset of trajectory A_kt[t]
>>> # Concatenate data into one timeseries.
>>> A_n = np.zeros([N], np.float32) # A_n[n] is nth sample in concatenated set of uncorrelated samples
>>> A_n[0:N_k[0]] = A_kn[0]
>>> for k in range(1,K): A_n[N_k[0:k].sum():N_k[0:k+1].sum()] = A_kn[k]
```

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

### pymbar.timeseries.detect_equilibration

Source: https://pymbar.readthedocs.io/en/stable/timeseries

Automatically detects the equilibrated region of a dataset by maximizing the number of effectively uncorrelated samples. It provides an estimate of the start of equilibrated data, the statistical inefficiency, and the maximum number of uncorrelated samples.

```APIDOC
## POST /pymbar/timeseries/detect_equilibration

### Description
Automatically detect equilibrated region of a dataset using a heuristic that maximizes number of effectively uncorrelated samples.

### Method
POST

### Endpoint
/pymbar/timeseries/detect_equilibration

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **A_t** (np.ndarray) - Required - timeseries
- **fast** (bool) - Optional - fast can be set to True to give a less accurate but very quick estimate (default: False)
- **nskip** (int) - Optional - number of samples to sparsify data by in order to speed equilibration detection (default: 1)

### Request Example
```json
{
  "A_t": "[1.0, 2.0, 3.0, 4.0, 5.0]",
  "fast": false,
  "nskip": 1
}
```

### Response
#### Success Response (200)
- **t** (int) - start of equilibrated data
- **g** (float) - statistical inefficiency of equilibrated data
- **Neff_max** (float) - number of uncorrelated samples

#### Response Example
```json
{
  "t": 10,
  "g": 1.5,
  "Neff_max": 100.0
}
```

### Notes
If your input consists of some period of equilibration followed by a constant sequence, this function treats the trailing constant sequence as having Neff = 1.
```

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

### MBAR Initialization with Custom Options

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the MBAR class with custom parameters such as maximum iterations, relative tolerance, verbosity, initial free energies, and solver protocol. These options allow fine-tuning of the MBAR convergence and calculation process.

```python
from pymbar import MBAR
import numpy as np

# Example data
u_kn = np.array([[...], [...]])
N_k = np.array([...])

# Custom options
max_iter = 5000
rel_tol = 1e-8
verbose = True
initial_f_k = np.array([0.0, 0.0]) # Example initial guess
solver_protocol = 'robust'

mbar = MBAR(u_kn, N_k, 
            maximum_iterations=max_iter, 
            relative_tolerance=rel_tol, 
            verbose=verbose, 
            initial_f_k=initial_f_k, 
            solver_protocol=solver_protocol)

```

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

### Get FES Confidence Intervals

Source: https://pymbar.readthedocs.io/en/stable/fes_with_pymbar

Calculates the confidence intervals for the Free Energy Surface (FES) at specified data points. It returns the values at the lower percentile, upper percentile, and the median.

```python
plow_values, phigh_values, median_values, all_values = fes.get_confidence_intervals(xplot, plow=0.025, phigh=0.975, reference='zero')
# plow_values, phigh_values, median_values, all_values are numpy arrays
```

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

### MBAR Class Initialization with Energy Data

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the MBAR class using reduced potential energy data (u_kn) and the number of samples per state (N_k). This is the primary method for setting up MBAR analysis. It computes dimensionless free energies upon initialization.

```python
from pymbar import MBAR
import numpy as np

# Example data (replace with your actual data)
u_kn = np.array([[...], [...]]) # Shape (K, N_max)
N_k = np.array([...]) # Shape (K,)

mbar = MBAR(u_kn, N_k)

```

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

### MBAR Initialization

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the MBAR object with potential energy data and simulation parameters.

```APIDOC
## MBAR Constructor

### Description
Initializes the MBAR object with potential energy data and simulation parameters.

### Method
`MBAR(u_kn, N_k, ...)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **u_kn** (list of lists or np.ndarray) - Potential energies for each state and sample.
- **N_k** (list or np.ndarray) - Number of samples for each state.
- **bootstrap_solver_protocol** (dict, string, or None, optional) - Protocol for bootstrap solver. Defaults to dict(method='adaptive', options=dict(min_sc_iter=0)).
- **rseed** (int or None, optional) - Seed for random number generation. Defaults to None.

### Request Example
```python
from pymbar import MBAR
from pymbar import testsystems

(x_n, u_kn, N_k, s_n) = testsystems.HarmonicOscillatorsTestCase().sample(mode='u_kn')
mbar = MBAR(u_kn, N_k)
```

### Response
#### Success Response (200)
MBAR object initialized.

#### Response Example
(No direct response, object is created in memory)
```

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

### MBAR Bootstrap Solver Protocol Configuration

Source: https://pymbar.readthedocs.io/en/stable/strategies_for_solution

Customize the solver sequence for bootstrapped solutions using the `bootstrap_solver_protocol` keyword. The default protocol uses an adaptive method with specific tolerance and iteration options.

```python
default_protocol = (
    dict(method="adaptive", tol = 1e-6, options=dict(min_sc_iter=0, maximum_iterations=100))
)

mbar = MBAR(..., n_bootstraps=100, uncertainty_method='bootstrap', bootstrap_solver_protocol=default_protocol)
```

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

### pymbar.timeseries.detect_equilibration_binary_search

Source: https://pymbar.readthedocs.io/en/stable/timeseries

Automatically detects the equilibrated region of a dataset using a binary search heuristic to maximize the number of effectively uncorrelated samples. It returns the start of the equilibrated data, statistical inefficiency, and the maximum number of uncorrelated samples.

```APIDOC
## POST /pymbar/timeseries/detect_equilibration_binary_search

### Description
Automatically detect equilibrated region of a dataset using a heuristic that maximizes number of effectively uncorrelated samples.

### Method
POST

### Endpoint
/pymbar/timeseries/detect_equilibration_binary_search

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **A_t** (np.ndarray) - Required - timeseries
- **bs_nodes** (int > 4) - Optional - number of geometrically distributed binary search nodes (default: 10)

### Request Example
```json
{
  "A_t": "[1.0, 2.0, 3.0, 4.0, 5.0]",
  "bs_nodes": 10
}
```

### Response
#### Success Response (200)
- **t** (int) - start of equilibrated data
- **g** (float) - statistical inefficiency of equilibrated data
- **Neff_max** (float) - number of uncorrelated samples

#### Response Example
```json
{
  "t": 15,
  "g": 1.2,
  "Neff_max": 95.0
}
```

### Notes
Finds the discard region (t) by a binary search on the range of possible lagtime values, with logarithmic spacings. This will give a local maximum. The global maximum is not guaranteed, but will likely be found if the N_eff[t] varies smoothly.
```

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

### Configure Bootstrap Solver Protocol for Uncertainty Calculation (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/strategies_for_solution.rst

Specifies the solver protocol to be used when calculating uncertainties via bootstrapping. This allows for customized optimization strategies tailored for the bootstrap resampling process, ensuring consistent and accurate error estimation.

```python
bootstrap_solver_protocol
```

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

### Initialize MBAR and compute free energy differences (pymbar v4)

Source: https://pymbar.readthedocs.io/en/stable/moving_from_pymbar3

Illustrates the updated method for initializing MBAR and computing free energy differences in pymbar version 4.0. It showcases the new dictionary-based return format for results and errors.

```python
mbar = MBAR(u_kn, N_k)
results = mbar.compute_free_energy_differences()
print(results['Delta_f'])
print(results['dDelta_f'])
```

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

### Calculate free energy difference using BAR estimator (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/moving_from_pymbar3.rst

Example of calculating the free energy difference using the BAR estimator in pymbar. This snippet illustrates the dictionary return format for the 'bar' function, providing the free energy difference and its uncertainty.

```python
results = bar(w_F, w_R)
print(f'Free energy difference is {results['Delta_f']:.3f} +- {results['Delta_f']:.3f} kT')
```

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

### Configure Bootstrap Solver Protocol (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/strategies_for_solution.rst

Defines the configuration for the bootstrap solver protocol using a dictionary. It specifies the 'adaptive' method, a tolerance of 1e-6, and solver options including a minimum of 0 iterations and a maximum of 100 iterations. This configuration is suitable for analyzing bootstrapped data where solutions need to be close but not as precise as the original dataset.

```python
bootstrap_solver_protocol = (dict(method="adaptive", tol = 1e-6, options=dict(min_sc_iter=0,maximum_iterations=100)))
```

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

### Configure MBAR Solver Protocol with Sequential Methods (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/strategies_for_solution.rst

Defines a solver protocol for MBAR calculations, specifying a sequence of methods ('hybr', 'L-BFGS-B', 'adaptive') with their respective tolerances and options. This allows for a robust optimization process where a failure in one method can be handled by subsequent methods.

```python
solver_protocol = (
        dict(method="hybr"),
        dict(method="L-BFGS-B", tol = 1.0e-5, continuation = True, options=dict(maxiter=1000)),
        dict(method="adaptive", tol = 1.0e-12, options=dict(maxiter=1000,min_sc_iter=5))
    )
```

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

### Detect Equilibration and Subsample Timeseries Data (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/timeseries.rst

Detects the equilibrated production region in a timeseries and subsamples it to obtain uncorrelated data. It returns the start index of the production region, the statistical inefficiency, and the maximum effective number of uncorrelated samples. The `nskip` parameter can be used to speed up computation by checking fewer time origins.

```python
from pymbar import timeseries
t0, g, Neff_max = timeseries.detect_equilibration(A_t) # compute indices of uncorrelated timeseries
A_t_equil = A_t[t0:]
indices = timeseries.subsample_correlated_data(A_t_equil, g=g)
A_n = A_t_equil[indices]
```

```python
nskip = 10 # only try every 10 samples for time origins
t0, g, Neff_max = timeseries.detect_equilibration(A_t, nskip=nskip)
```

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

### Detect Equilibration of Timeseries Data (Python)

Source: https://pymbar.readthedocs.io/en/stable/timeseries

Automatically detects the equilibrated region of a timeseries dataset using a heuristic to maximize the number of effectively uncorrelated samples. It returns the start index of the equilibrated data, the statistical inefficiency, and the maximum number of uncorrelated samples. The 'fast' parameter allows for a quicker but less accurate estimation, and 'nskip' can be used to sparsify data for faster detection.

```python
from pymbar import testsystems
from pymbar.timeseries import detect_equilibration

A_t = testsystems.correlated_timeseries_example(N=1000, tau=5.0) # generate a test correlated timeseries
[t, g, Neff_max] = detect_equilibration(A_t) # compute indices of uncorrelated timeseries

A_t = testsystems.correlated_timeseries_example(N=1000, tau=5.0) + 2.0 # generate a test correlated timeseries
B_t = testsystems.correlated_timeseries_example(N=10000, tau=5.0) # generate a test correlated timeseries
C_t = np.concatenate([A_t, B_t])
[t, g, Neff_max] = detect_equilibration(C_t, nskip=50) # compute indices of uncorrelated timeseries
```

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

### MBAR Initialization with Bootstrap Analysis

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the MBAR class and sets up for bootstrap analysis to compute uncertainties in free energy differences. The n_bootstraps parameter specifies the number of bootstrap replicates to perform.

```python
from pymbar import MBAR
import numpy as np

# Example data
u_kn = np.array([[...], [...]])
N_k = np.array([...])

# Number of bootstrap replicates
num_bootstraps = 100

mbar = MBAR(u_kn, N_k, n_bootstraps=num_bootstraps)

```

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

### Detect Equilibration using Binary Search (Python)

Source: https://pymbar.readthedocs.io/en/stable/timeseries

Automatically detects the equilibrated region of a dataset by employing a binary search strategy on lagtime values to maximize the number of effectively uncorrelated samples. This method aims to find a local maximum for the number of uncorrelated samples, and while a global maximum is not guaranteed, it is likely to be found if the N_eff[t] varies smoothly. It returns the start of the equilibrated data, the statistical inefficiency, and the maximum number of uncorrelated samples.

```python
from pymbar.timeseries import detect_equilibration_binary_search

# Assuming A_t is a numpy array representing the timeseries
# [t, g, Neff_max] = detect_equilibration_binary_search(A_t, bs_nodes=10)
```

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

### MBAR Class Documentation

Source: https://pymbar.readthedocs.io/en/stable/_sources/mbar.rst

Documentation for the MBAR class, including its methods and attributes, as implemented in the pymbar.mbar module.

```APIDOC
## MBAR Class

### Description
Implements the multistate Bennett acceptance ratio (MBAR) method.

### Method
N/A (Class Documentation)

### Endpoint
N/A (Class Documentation)

### Parameters
N/A (Class Documentation)

### Request Example
N/A (Class Documentation)

### Response
#### Success Response (200)
N/A (Class Documentation)

#### Response Example
N/A (Class Documentation)
```

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

### Initialize MBAR and compute free energy differences (pymbar v3)

Source: https://pymbar.readthedocs.io/en/stable/moving_from_pymbar3

Demonstrates how to initialize the MBAR object and retrieve free energy differences in pymbar version 3.x. It shows the older tuple-based return format.

```python
mbar = MBAR(u_kn, N_k)
results, errors = mbar.getFreeEnergyDifferences()
print(results[0])
print(errors[0])
```

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

### MBAR Initialization with BAR Initialization

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the MBAR class using the BAR (Bennett Acceptance Ratio) method for pairwise states to initialize the free energies. This option is best when states are ordered to maximize overlap.

```python
from pymbar import MBAR
import numpy as np

# Example data
u_kn = np.array([[...], [...]])
N_k = np.array([...])

mbar = MBAR(u_kn, N_k, initialize='BAR')

```

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

### Compute Expectations with MBAR (Python)

Source: https://pymbar.readthedocs.io/en/stable/mbar

Demonstrates how to use the MBAR class to compute expectations of observables. It shows sampling data, initializing MBAR, and then calling compute_expectations with different output modes ('averages' and 'differences').

```python
from pymbar import testsystems
from pymbar import MBAR

# Sample data from a test system
(x_n, u_kn, N_k, s_n) = testsystems.HarmonicOscillatorsTestCase().sample(mode='u_kn')

# Initialize MBAR
mbar = MBAR(u_kn, N_k)

# Compute expectations for 'averages' output
A_n = x_n
results = mbar.compute_expectations(A_n)

# Compute expectations for 'differences' output
A_n = u_kn[0,:]
results = mbar.compute_expectations(A_n, output='differences')
```

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

### MBAR Class Initialization

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the Multistate Bennett Acceptance Ratio (MBAR) method for analyzing simulation data. This involves computing dimensionless free energies for all states.

```APIDOC
## MBAR Class

### Description
Initializes the multistate Bennett acceptance ratio (MBAR) method for the analysis of multiple equilibrium samples. Upon initialization, the dimensionless free energies for all states are computed.

### Method
__init__

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **u_kn** (np.ndarray, float, shape=(K, N_max)) - Required - `u_kn[k,n]` is the reduced potential energy of uncorrelated configuration n evaluated at state `k`.
* **u_kln** (np.ndarray, float, shape=(K, L, N_max)) - Optional - If the simulation is in form `u_kln[k,l,n]` it is converted to `u_kn` format.
* **N_k** (np.ndarray, int, shape=(K,)) - Required - `N_k[k]` is the number of uncorrelated snapshots sampled from state `k`.
* **maximum_iterations** (int) - Optional - Set to limit the maximum number of iterations performed (default 10000).
* **relative_tolerance** (float) - Optional - Set to determine the relative tolerance convergence criteria (default 1.0e-7).
* **verbosity** (bool) - Optional - Set to True if verbose debug output is desired (default False).
* **initial_f_k** (np.ndarray, float, shape=(K,)) - Optional - Set to the initial dimensionless free energies to use as a guess (default None, which sets all f_k = 0).
* **solver_protocol** (list[dict] or string or None) - Optional - List of dictionaries to define a sequence of solver algorithms and options used to estimate the dimensionless free energies. If None, use the developers best guess at an appropriate algorithm.
* **initialize** ('zeros' or 'BAR') - Optional - If equal to ‘BAR’, use bar between the pairwise state to initialize the free energies. Default: 'zeros'.
* **x_kindices** (np.ndarray, int, shape=(K,)) - Optional - Describes which state is each sample _x_ is from? Default: [0, 1, 2, ... K-1].
* **n_bootstraps** (int) - Optional - How many bootstrap free energies will be computed? If None, no bootstraps will be computed. Default: 0.

### Request Example
```json
{
  "u_kn": [[1.0, 2.0], [3.0, 4.0]],
  "N_k": [10, 10],
  "maximum_iterations": 5000,
  "relative_tolerance": 1e-6,
  "verbosity": true,
  "initialize": "BAR"
}
```

### Response
#### Success Response (200)
* **MBAR object** - An initialized MBAR object containing computed free energies and other relevant data.

#### Response Example
```json
{
  "message": "MBAR object initialized successfully."
}
```
```

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

### FES Class Initialization

Source: https://pymbar.readthedocs.io/en/stable/fes_with_pymbar

Initializes the FES class for free energy surface calculations using MBAR on simulation data from K states. It computes dimensionless free energies and creates an internal MBAR object.

```APIDOC
## FES Class Initialization

### Description
Initializes a free energy surface calculation by performing multistate Bennett acceptance ratio (MBAR) on a set of simulation data from umbrella sampling at K states. Upon initialization, the dimensionless free energies for all states are computed. This may take anywhere from seconds to minutes, depending upon the quantity of data. This also creates an internal mbar object that is used to create the free energy surface.

### Method
`pymbar.FES(_u_kn_ , _N_k_ , _verbose =False_, _mbar_options =None_, _timings =True_, _** kwargs_)

### Parameters
#### Path Parameters
- **u_kn** (np.ndarray, float, shape=(K, N_max)) - `u_kn[k,n]` is the reduced potential energy of uncorrelated configuration n evaluated at state `k`.
- **N_k** (np.ndarray, int, shape=(K)) - `N_k[k]` is the number of uncorrelated snapshots sampled from state `k`. Some may be zero, indicating that there are no samples from that state.
- **verbose** (bool) - Optional flag for verbose output.
- **mbar_options** (dict) - Options supported by MBAR, including `maximum_iterations`, `relative_tolerance`, `verbosity`, `initial_f_k`, `solver_protocol`, and `initialize`.
- **timings** (bool) - Optional flag to enable timing information.

### Request Example
```python
from pymbar import testsystems
(x_n, u_kn, N_k, s_n) = testsystems.HarmonicOscillatorsTestCase().sample(mode='u_kn')
 fes = FES(u_kn, N_k)
```

### Response
#### Success Response (200)
- **FES object**: An initialized FES object ready for generating free energy surfaces.

#### Response Example
```json
{
  "message": "FES object initialized successfully"
}
```
```

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

### MBAR Class Initialization with u_kln Data

Source: https://pymbar.readthedocs.io/en/stable/mbar

Initializes the MBAR class using potential energy data in the u_kln format, where u_kln[k,l,n] is the reduced potential energy of configuration n evaluated at state l, sampled from state k. This format is converted internally to u_kn.

```python
from pymbar import MBAR
import numpy as np

# Example data (replace with your actual data)
u_kln = np.array([[[...]]]) # Shape (K, L, N_max)
N_k = np.array([...]) # Shape (K,)

mbar = MBAR(u_kln=u_kln, N_k=N_k)

```

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

### Generate Free Energy Surface

Source: https://pymbar.readthedocs.io/en/stable/fes_with_pymbar

Generates a free energy surface using various methods like histogram, KDE, or spline approximation based on provided simulation data.

```APIDOC
## Generate Free Energy Surface

### Description
Generates a free energy surface using the initialized MBAR object. It supports multiple methods for estimating the continuous function from the samples, including histogram, kernel density estimation (KDE), and spline approximation.

### Method
`generate_fes(_u_n_ , _x_n_ , _fes_type ='histogram'_, _histogram_parameters =None_, _kde_parameters =None_, _spline_parameters =None_, _n_bootstraps =0_, _seed =-1_)

### Parameters
#### Path Parameters
- **u_n** (np.ndarray) - Energies at the sampled points.
- **x_n** (np.ndarray) - Coordinates of the sampled points.
- **fes_type** (str) - The method to use for generating the FES. Options: 'histogram', 'kde', 'spline'. Defaults to 'histogram'.
- **histogram_parameters** (dict) - Parameters for the histogram method.
- **kde_parameters** (dict) - Parameters for the KDE method, passed to `sklearn.neighbors.KernelDensity`.
- **spline_parameters** (dict) - Parameters for the spline method.
- **n_bootstraps** (int) - Number of bootstrap samples to generate for uncertainty estimation. Defaults to 0.
- **seed** (int) - Random seed for bootstrapping. Defaults to -1 (no seed).

### Request Example
```python
# Assuming 'fes' is an initialized FES object
# Example using histogram method
fes_histogram = fes.generate_fes(u_n, x_n, fes_type='histogram')

# Example using KDE method with custom parameters
kde_params = {'bandwidth': 0.5}
fes_kde = fes.generate_fes(u_n, x_n, fes_type='kde', kde_parameters=kde_params)
```

### Response
#### Success Response (200)
- **FES object**: An object containing the generated free energy surface information, including methods to retrieve values and uncertainties.

#### Response Example
```json
{
  "message": "Free energy surface generated successfully"
}
```
```

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

### Initialize Free Energy Surface Calculation with pymbar.FES

Source: https://pymbar.readthedocs.io/en/stable/fes_with_pymbar

Initializes the pymbar.FES class to perform Multistate Bennett Acceptance Ratio (MBAR) on simulation data from umbrella sampling. It computes dimensionless free energies and creates an internal MBAR object for FES generation. Assumes data are uncorrelated; subsampling is required for correlated data.

```python
from pymbar import FES
from pymbar import testsystems

# Example usage:
(x_n, u_kn, N_k, s_n) = testsystems.HarmonicOscillatorsTestCase().sample(mode='u_kn')

# Initialize FES with energy data and sample counts
fes = FES(u_kn, N_k)
```

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

### Enable logging in pymbar (Python)

Source: https://pymbar.readthedocs.io/en/stable/_sources/moving_from_pymbar3.rst

Configures the logging module to direct pymbar messages to standard output. This is necessary for viewing informational messages when the verbose flag is set to True, replacing the previous behavior of sending messages directly to stdout.

```python
import logging
import sys
logging.basicConfig(stream=sys.stdout, level=logging.INFO)
```

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

### sample_parameter_distribution

Source: https://pymbar.readthedocs.io/en/stable/fes_with_pymbar

Samples the values of the spline parameters using Monte Carlo (MC) simulation.

```APIDOC
## POST /sample_parameter_distribution

### Description
Samples the values of the spline parameters with MC. This function is used to explore the parameter space of the model.

### Method
POST

### Endpoint
/sample_parameter_distribution

### Parameters
#### Path Parameters
- **x_n** (numpy.ndarray) - Required - D-dimensional array representing the FES dimensionality.

#### Request Body
- **mc_parameters** (dict, optional) - Dictionary containing MC simulation parameters:
  - **niterations** (int) - Number of iterations for the MC procedure.
  - **fraction_change** (float) - Fraction of the input parameter range used for new MC moves.
  - **sample_every** (int) - Frequency (in steps) at which the MC timeseries is saved.
  - **print_every** (int) - Frequency (in steps) at which MC timeseries is logged.
  - **logprior** (function) - The logprior function that takes a single array argument (parameters).
- **decorrelate** (boolean, optional) - Whether to decorrelate the output time series. Defaults to True.
- **verbose** (boolean, optional) - Whether to print detailed information to the logger. Defaults to True.

### Request Example
```json
{
  "x_n": [1.0, 2.0, 3.0],
  "mc_parameters": {
    "niterations": 5000,
    "fraction_change": 0.05,
    "sample_every": 5,
    "print_every": 50,
    "logprior": "def logprior(params): return -0.5 * np.sum(params**2)"
  },
  "decorrelate": true,
  "verbose": false
}
```

### Response
#### Success Response (200)
- **message** (str) - Indicates successful sampling.

#### Response Example
```json
{
  "message": "Parameter sampling completed successfully."
}
```
```
Tokens:
Raw