ForceMatchingRegressor¶
- class openxps.ForceMatchingRegressor(dynamical_variables, num_kernels, *, validation_fraction=0.1, batch_size=256, num_epochs=50, patience=10, learning_rate=0.002, weight_decay=0.0001, accelerator='auto', devices=1, num_workers=0, verbose=False)[source]¶
Potential regressor from sampled position/force pairs.
A potential function in a \(d\)-dimensional variable space is approximated as:
\[U({\bf s}) = \sum_{m=1}^n w_m \exp\left( -\frac{1}{2} \sum_{k=1}^d \frac{\delta_k^2(s_k - c_{m,k})}{\sigma_{m,k}^2} \right)\]where the \(n\) weights \(w_m\), kernel bandwidths \(\sigma_m\), and kernel centers \({\bf c}_m\) are adjustable parameters. The displacement function \(\delta_k(x)\) depends on the periodicity of the variable \(s_k\) and is defined as:
\[\begin{split}\delta_k(x) = \left\{\begin{array}{ll} x & \text{if }s_k\text{ is non-periodic} \\ \frac{L_k}{\pi}\sin(\frac{\pi x}{L_k}) & \text{if }s_k\text{ has period }L_k \end{array}\right.\end{split}\]Given \(N\) position-force pairs \(({\bf s}_i, {\bf F}_i)\), the parameters are adjusted by minimizing the mean squared error loss:
\[L = \frac{1}{Nd} \sum_{i=1}^N \left\|{\bf f}({\bf s}_i) - {\bf F}_i\right\|^2,\]where \(d\) is the number of dynamical variables and \({\bf f}({\bf s}) = -\nabla_{\bf s} U({\bf s})\) is the predicted force.
- Parameters:
dynamical_variables (Sequence[DynamicalVariable]) – The dynamical variables to be used in the potential. They are converted to the MD unit system, so the positions and forces passed to
fit()andpredict()must be expressed in MD units.num_kernels (int) – The number of kernels to be used in the potential.
- Keyword Arguments:
validation_fraction – The fraction of the data to be used for validation.
batch_size – The batch size to be used for training.
num_epochs – The number of epochs to be used for training.
patience – The patience for early stopping.
learning_rate – The learning rate to be used for training.
weight_decay – The weight decay to be used for training.
accelerator – The accelerator to be used for training. Valid options can be found here.
devices – The number of devices, or
"auto", passed to the Lightning trainer. The default of 1 avoids launching distributed training on multi-GPU hosts.num_workers – The number of data loading workers to be used for training.
verbose – Whether
fit()shows Lightning’s progress bar, model summary and informational messages.
Methods
- fit(positions, forces, *, seed=None)[source]¶
Fit the potential regressor to the given positions and forces.
- Parameters:
positions (ArrayLike) – An array of shape (N, d) with the positions in MD units.
forces (ArrayLike) – An array of shape (N, d) with the forces in MD units.
- Keyword Arguments:
seed – The seed used to split the data, shuffle the batches and initialize the kernels. If None, a random seed is used. The global random states of NumPy and PyTorch are left untouched.
Notes
The fitted model and learning curve replace the previous ones only if training completes, so a failed fit leaves the regressor unchanged.
- get_learning_curve()[source]¶
Get the learning curve of the last fit.
- Returns:
A copy of the per-epoch losses, with columns
epoch,train_lossand, when a validation set is used,val_loss.- Return type:
pd.DataFrame
- Raises:
RuntimeError – If
fit()has not been called.
- get_parameters()[source]¶
Get the parameters of the potential regressor.
- Returns:
centers – The centers of the radial basis functions, shape (M, d).
sigmas – The bandwidths of the radial basis functions per dimension, shape (M, d).
weights – The weights of the radial basis functions, shape (M,).
- Return type:
tuple[ndarray, ndarray, ndarray]
Notes
Centers of periodic variables are wrapped into their bounds. Centers of non-periodic variables are returned as fitted, even if they lie outside the bounds, because the kernels use plain displacements for those variables.
- Raises:
RuntimeError – If
fit()has not been called.- Return type:
tuple[ndarray, ndarray, ndarray]