User Guide#

This user guide provides detailed information on the various modules available in the CRISP package, along with performance tips to help optimize their usage.

CRISP is organized into two main subpackages:

  • simulation_utility: Tools for preparing and processing simulation data

  • data_analysis: Methods for analyzing simulation results

Simulation Utility Modules#

1. Atomic Indices Classification#

Module: CRISP.simulation_utility.atomic_indices

This module allows for the classification of atoms based on custom-defined indices, making it easier to analyze specific subsets within your simulation data.

Key Features:

  • Customizable classification based on distance criteria

  • Automatic generation of atom type indices

  • Cutoff-based neighbor identification

Example Usage:

from CRISP.simulation_utility.atomic_indices import run_atom_indices

cutoffs = {
    ("O", "H"): 1.2,
    ("Si", "O"): 1.8,
    ("Al", "Si"): 3.2,
    ("O", "O"): 3.0,
}

run_atom_indices("./wrapped_traj.traj", "./indices_new/",
                 frame_index=2, cutoffs=cutoffs)

Performance Tips:

  • Choose appropriate cutoff distances to balance accuracy and computational cost

  • Use frame_index parameter to analyze representative frames instead of entire trajectories

2. Atomic Trajectory Visualization#

Module: CRISP.simulation_utility.atomic_traj_linemap

Visualizes atomic trajectories in 3D to understand motion and structural changes.

Key Features:

  • Interactive 3D visualization of atomic trajectories

  • Customizable frame skipping and atom selection

  • HTML output for web-based visualization

Example Usage:

from CRISP.simulation_utility.atomic_traj_linemap import plot_atomic_trajectory
import numpy as np

oxygen_indices = np.load("./indices_detailed/ex_fram_ox.npy")
plot_atomic_trajectory(
    traj_path="./wrapped_traj.traj",
    selected_indices=oxygen_indices,
    output_path="oxygen_trajectories.html",
    frame_skip=10
)

Performance Tips:

  • Use frame_skip to reduce computational load for long trajectories

  • Select specific atom indices rather than visualizing all atoms

3. Subsampling#

Module: CRISP.simulation_utility.subsampling

Extract representative structures from trajectories using Farthest Point Sampling with SOAP descriptors.

Key Features:

  • SOAP-descriptor based diversity assessment

  • Farthest Point Sampling for systematic subset selection

  • Convergence visualization

Example Usage:

from CRISP.simulation_utility.subsampling import subsample

all_frames = subsample(
    filename="./trajectory.traj",
    n_samples=30,
    index_type="all",
    file_format="traj",
    skip=10,
    plot_subsample=True
)

Performance Tips:

  • Use convergence plots to determine optimal subset size

  • Consider computational budget vs. required accuracy when selecting n_samples

4. Error Analysis#

Module: CRISP.simulation_utility.error_analysis

Perform statistical error analysis on time-correlated simulation data using autocorrelation function and block averaging methods.

Key Features:

  • Autocorrelation function analysis with τ_int calculation

  • Block averaging with convergence assessment

  • Comprehensive statistical uncertainty estimation

Example Usage:

from CRISP.simulation_utility.error_analysis import error_analysis
import numpy as np

data = np.load("energy.npy")
res = error_analysis(data)
print(res["acf_results"])
print(res["block_results"])

Performance Tips:

  • Use autocorrelation analysis for statistically rigorous error estimation

  • Compare ACF and block averaging results for validation

5. Interatomic Distance Calculation#

Module: CRISP.simulation_utility.interatomic_distances

Calculate and save distance matrices between atoms for further analysis.

Key Features:

  • Periodic boundary condition handling

  • Selective atom type analysis

  • Distance matrix storage for reuse

Example Usage:

from CRISP.simulation_utility.interatomic_distances import distance_calculation, save_distance_matrices

full_dms, sub_dms = distance_calculation("./wrapped_traj.traj",
                                       frame_skip=10, index_type=["O"])
save_distance_matrices(full_dms, sub_dms, ["O"],
                      output_dir="distance_calculations")

Performance Tips:

  • Use frame_skip to reduce computational load

  • Focus on specific atom types rather than all atoms

Data Analysis Modules#

1. Contact and Coordination Analysis#

Module: CRISP.data_analysis.contact_coordination

Analyze coordination environments and dynamic contacts between atoms.

Key Features:

  • Coordination number analysis with custom cutoffs

  • Contact persistence analysis

  • Interactive visualization with heatmaps

Example Usage:

from CRISP.data_analysis.contact_coordination import coordination, contacts

# Coordination analysis
cn = coordination("./wrapped_traj.traj", "O", ["O"],
                 {('O', 'O'): 2.5}, skip_frames=10, plot_cn=True)

# Contact analysis
sub_dm, cal_contacts = contacts("./wrapped_traj.traj", "O", ["O"],
                               {('O', 'O'): 2.5}, plot_contacts=True)

Performance Tips:

  • Use appropriate cutoffs based on chemical knowledge

  • Skip frames for long trajectories to reduce computation time

2. Hydrogen Bond Analysis#

Module: CRISP.data_analysis.h_bond

Analyze hydrogen bond networks using geometric criteria based on angle and distance cutoffs.

Key Features:

  • Geometric criteria (angle and distance based)

  • Network visualization and correlation matrices

  • Time series analysis of H-bond counts

Example Usage:

from CRISP.data_analysis.h_bond import hydrogen_bonds

h_bonds_per_frame = hydrogen_bonds(
    traj_path="./wrapped_traj.traj",
    frame_skip=10,
    acceptor_atoms=["O"],
    angle_cutoff=120,
    h_bond_cutoff=2.5,
    bond_cutoff=1.6,
    plot_count=True,
    plot_heatmap=True,
    plot_graph_frame=True
)

Performance Tips:

  • Use relaxed cutoffs for initial screening, then refine parameters

  • Enable specific plots based on analysis needs to save computation time

3. Radial Distribution Function (RDF)#

Module: CRISP.data_analysis.prdf

Calculate radial distribution functions for spatial relationship analysis.

Key Features:

  • Partial RDF (PRDF) calculation for specific atom pairs

  • Automatic binning and periodic boundary condition handling

  • Interactive and static visualization options

Example Usage:

from CRISP.data_analysis.prdf import analyze_rdf

result = analyze_rdf(
    use_prdf=True,
    rmax=6,
    traj_path="./trajectory.traj",
    nbins=50,
    frame_skip=100,
    atomic_indices=(pt_indices, pt_indices),
    create_plots=True
)

Performance Tips:

  • Adjust rmax to focus on relevant distance ranges

  • Use frame_skip for long trajectories

  • Limit analysis to essential atom pairs

4. Mean Square Displacement (MSD)#

Module: CRISP.data_analysis.msd

Calculate and analyze Mean Square Displacement to study diffusion properties.

Key Features:

  • Two-step analysis: MSD calculation and diffusion coefficient extraction

  • Linear fitting with statistical error estimation

  • Visual representation with fit lines

Example Usage:

from CRISP.data_analysis.msd import calculate_save_msd, analyze_from_csv

# Step 1: Calculate MSD
msd_values, msd_times = calculate_save_msd(
    traj_file="./trajectory.traj",
    timestep_value=5000.0,
    indices_file="./indices.npy",
    output_file="msd_results.csv"
)

# Step 2: Analyze diffusion
D, error = analyze_from_csv("msd_results.csv", plot_msd=True)

Performance Tips:

  • Use representative atom selection instead of all atoms

  • Consider trajectory subsampling for very long simulations

5. Clustering Analysis#

Module: CRISP.data_analysis.clustering

Identify atomic clusters using DBSCAN clustering algorithms.

Key Features:

  • DBSCAN clustering with periodic boundary conditions

  • Single-frame and trajectory-based analysis

  • 3D visualization and cluster statistics

Example Usage:

from CRISP.data_analysis.clustering import analyze_frame, analyze_trajectory

# Single frame analysis
analyzer = analyze_frame(
    traj_path="./trajectory.traj",
    atom_indices="./indices.npy",
    threshold=2.6,
    min_samples=2,
    custom_frame_index=8100
)
result = analyzer.analyze_structure(output_dir="clustering_results")

# Trajectory analysis
analysis_results = analyze_trajectory(
    traj_path="./trajectory.traj",
    indices_path="./indices.npy",
    threshold=3.0,
    min_samples=2,
    frame_skip=100
)

Performance Tips:

  • Tune threshold and min_samples parameters based on physical understanding

  • Use frame_skip for trajectory analysis to reduce computational load

  • Consider using different thresholds to explore various connectivity definitions

6. Volumetric Density#

Module: CRISP.data_analysis.volumetric_atomic_density

Create 3D volumetric density maps to visualize the spatial distribution of atoms throughout a trajectory.

Key Features:

  • 3D density mapping with interactive visualizations

  • Optional 2D projections (XY, YZ, XZ) for cross-sectional analysis

  • Flexible thresholding (relative or absolute)

  • Data export in NPZ format for further analysis

  • Framework integration with selective atom visualization

Example Usage:

from CRISP.data_analysis.volumetric_atomic_density import create_density_map

# Basic density map with projections
fig = create_density_map(
    traj_path="./trajectory.traj",
    indices_path="./atom_indices.npy",
    frame_skip=100,
    threshold=0.05,
    opacity=0.8,
    show_projections=True,
    save_density=True,
    output_dir="./density_analysis",
    output_file="density_map.html"
)

# Comparative analysis with different projection modes
projection_options = [True, False]
for show_projections in projection_options:
    proj_text = "with_projections" if show_projections else "no_projections"
    create_density_map(
        traj_path="./trajectory.traj",
        indices_path="./indices.npy",
        frame_skip=100,
        threshold=0.0,
        opacity=0.8,
        show_projections=show_projections,
        save_projection_images=show_projections,
        output_dir="./density_comparison",
        output_file=f"density_{proj_text}.html"
    )

Performance Tips:

  • Use appropriate frame_skip values to balance accuracy and computational efficiency

  • Start with threshold=0.0 to see all density regions, then adjust for focus areas

  • Use save_density=True to avoid recomputation when adjusting visualization parameters

  • Consider omit_static_indices to focus on mobile species in complex systems

  • Adjust nbins parameter based on system size and required resolution

Applications:

  • Zeolite guest molecule distribution analysis

  • Diffusion pathway identification in porous materials

  • Adsorption site characterization

  • Phase behavior studies in confined systems

  • Structural flexibility analysis

General Performance Tips#

Memory Management:

  • Use frame skipping for long trajectories

  • Focus analysis on specific atom types or regions of interest

  • Save intermediate results to avoid recomputation

Parallel Processing:

  • Consider using multiple cores for trajectory analysis

  • Batch process multiple systems or conditions

  • Use efficient data structures (numpy arrays) for large datasets

Parameter Optimization:

  • Start with reasonable default parameters based on chemical knowledge

  • Use convergence plots and validation against experimental data

  • Perform sensitivity analysis to understand parameter effects

Further Reading#

For more detailed information, including advanced usage and troubleshooting, please refer to the Developer Guide and Tutorials.