Simulation Monitoring & Analysis

Overview

SPARC provides interactive modules for workflow inspection and analysis of active learning iterations. These tools allow monitoring of energetic/geometric properties from MD trajectories, as well as model reliability indicators (e.g., learning curves, force deviation, uncertainty).

The utilities are designed for Jupyter Notebook environments, integrating ipywidgets, matplotlib, and ASE.

Workflow Analysis

The workflow interface provides an interactive way to inspect outputs across multiple iterations, particularly useful for visualizing energetics and geometrical trends during training.

Features

Load and visualize per-iteration properties (temperature, energy, etc.) from trajectory files.
Interactive widgets for selecting root directory, subfolder, trajectory, and iterations.
Geometry analysis tab for plotting bond lengths or angles with user-defined indices.

Dependencies

numpy
matplotlib
ASE (Atomic Simulation Environment)

Quick Start

Launch a Jupyter Notebook.
Import and run the workflow interface:

from sparc.src.utils.workflow import WorkFlowAnalysis
WorkFlowAnalysis()

The interface will appear with tabs for: - Temperature - Total Energy - Potential Energy - Kinetic Energy - Geometry (Bond / Angle)
For each tab: - Set the root directory containing iter_xxxxxx folders. - Specify subfolder (default: 02.dpmd) and trajectory file (default: dpmd.traj). - Click Refresh Iterations to detect available folders. - Select iterations and generate plots.

Example Directory Layout

project_root/
├── iter_000000/
│   └── 02.dpmd/
│       └── dpmd.traj
├── iter_000001/
│   └── 02.dpmd/
│       └── dpmd.traj
└── iter_000002/
    └── 02.dpmd/
        └── dpmd.traj

Geometry Tab

Choose “Bond” or “Angle” type.
Provide atom indices (e.g., 0 1 or 0 1 2).
The y-axis will render the proper chemical symbols with subscripts.

Workflow

Advanced Analysis

Monitoring the training progress of the ML potential requires systematic evaluation of learning and predictive reliability. SPARC provides modules for analyzing physical and statistical indicators:

Learning curves: energy/force loss evolution.
Parity plots: comparison of predicted vs reference quantities.
Uncertainty metrics: ensemble variance, deviation in forces.
Physical observables: trajectory-based properties (temperature fluctuations).

Model Deviation in Forces

The model deviation metric quantifies how much an ensemble of models disagree on predicted forces. Large deviations signal regions of phase space where the model is uncertain and more training data is required.

Mathematical Definition:

\[\epsilon_{\mathbf{F}, i}(\mathbf{x}) = \sqrt{ \frac{1}{n_m} \sum_{k=1}^{n_m} \left\| \mathbf{F}_i^{(k)} - \bar{\mathbf{F}}_i \right\|^2 }\]

where:

\(\mathbf{F}_i^{(k)}\) = force on atom \(i\) from model \(k\)
\(\bar{\mathbf{F}}_i = \frac{1}{n_m} \sum_{k=1}^{n_m} \mathbf{F}_i^{(k)}\) = ensemble average force
\(n_m\) = number of models in the ensemble
\(\|\cdot\|\) = Euclidean norm