ISOKANN

The ISOKANN.jl package implements the ISOKANN algorithm for the identification of macro-states of molecular systems. Its main features comprise of:

• A flexible implementation of the ISOKANN core (Iso) (supporting 1D and N-D ISOKANN, customizable neural networks on a broad set of SimulationData)
• A battery-included interfaces to OpenMM for automated adaptive sampling of molecular dynamics
• Different adaptive sampling strategies (extapolation, kde and stratified sampling)
• A posteriori analysis tools (plots, reaction path extraction and reaction rate estimation)

See the documentation for details.

Quick start

Install the package via julia> ]add https://github.com/axsk/ISOKANN.jl.

If you want to use Julia's built Conda.jl to automatically install OpenMM, you shoud build the package after setting the environment variable PYTHON="", e.g. through ENV["PYTHON"]=""; using Pkg; Pkg.build().

The usual pipeline consists of the creation of system simulation, generation of training data, training ISOKANN and a posteriori analysis of the results.

using ISOKANN

# Define an OpenMMSimulation. The default molecule is the Alanine-Dipeptide.
sim = OpenMMSimulation()

# Sample the initial data for training of ISOKANN with 100 initial points and 5 koopman samples per point.
data = SimulationData(sim, 100, 5)

# create the ISOKANN training object
iso = Iso(data)

# train for 100 episodes
run!(iso, 100)

# plot the training losses and chi values
plot_training(iso)

# scatter plot of all initial points colored in corresponding chi value
scatter_ramachandran(iso)

# estimate the exit rates, i.e. the metastability
exit_rates(iso)

# extract the reactive path
save_reactive_path(iso, out="path.pdb")

In the case that the simulation data is already present, e.g. sampled externally, we can replace the data line above with either of

data = SimulationData(xs,ys) # For given initial points `xs` (D x N) and koopman samples `ys` (D x K x N)
data = SimulationData(data_from_trajectory(xs)) # If `xs` is a trajectory of size (D x N)
data = SimulationData(data_from_trajectories([xs1, xs2, ...]) # If each `xs_i` is a trajectory

More comprehensive usecase examples can be found in

• scripts/villin.jl: simulating the folding of the chicken villin
• scripts/vgvapg.jl
• `scripts/trpcaeg.jl
• `scripts/multitraj.jl: Extraction of reaction paths from multiple long trajectories.

For further information on specific functions use Julias built-in help/docstring functionality, e.g. ?Iso.

References

• Rabben, Ray, Weber (2018) - ISOKANN: Invariant subspaces of Koopman operators learned by a neural network.
• Sikorski, Ribera Borrell, Weber (2024) - Learning Koopman eigenfunctions of stochastic diffusions with optimal importance sampling and ISOKANN
• Sikorski, Rabben, Chewle, Weber (2024) - Capturing the Macroscopic Behaviour of Molecular Dynamics with Membership Functions