### Setup Virtual Environment and Install Dependencies

Source: https://github.com/kinisi-dev/kinisi/blob/main/CONTRIBUTING.md

Creates a Python virtual environment using virtualenvwrapper, navigates to the project directory, and installs development dependencies. Requires virtualenvwrapper and Python 3.8+. The [dev] extra includes testing and formatting tools.

```shell
mkvirtualenv kinisi
cd kinisi/
pip install .[dev]
```

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

### Compute diffusion coefficient with kinisi (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Sets a start time for the diffusion regime and runs kinisi's diffusion method, which returns a diffusion coefficient with an associated uncertainty.

```python
start_of_diffusion = 3000 * sc.Unit('fs')\nkinisi_diff.diffusion(start_of_diffusion, progress=False, random_state=rng)
```

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

### Start Jump Diffusion Analysis

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_dj.ipynb

Initiates the jump diffusion analysis using the estimated start time of the diffusive regime. The random_state argument ensures reproducibility of results. Dependencies include sc modules for unit handling.

```python
start_of_diffusion = 4000 * sc.Unit('fs')
diff.jump_diffusion(start_of_diffusion, progress=False, random_state=rng)
```

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

### Perform VTF Analysis for Super-Arrhenius (Python)

Source: https://context7.com/kinisi-dev/kinisi/llms.txt

This Python example analyzes super-Arrhenius diffusion using the Vogel-Fulcher-Tammann equation with MCMC fitting. It uses Kinisi, Scipp, and NumPy, inputting temperature-dependent diffusion data with variances to estimate parameters like activation energy and T0. Outputs include model comparison via Bayesian evidence, suitable for glass-forming systems but requires proper bounds.

```python
from kinisi.arrhenius import VogelFulcherTammann
import scipp as sc

# Same diffusion data as Arrhenius example
diffusion_data = sc.DataArray(
    data=D_values,
    coords={'temperature': temperatures},
    variances=D_variances.values
)

# Fit VTF relationship: D = D0 * exp(-Ea / k(T - T0))
vtf = VogelFulcherTammann(
    diffusion=diffusion_data,
    bounds=[
        (sc.scalar(0.1, unit='eV'), sc.scalar(2.0, unit='eV')),    # Ea bounds
        (sc.scalar(1e-8, unit='cm^2/s'), sc.scalar(1.0, unit='cm^2/s')),  # D0 bounds
        (sc.scalar(0.0, unit='K'), sc.scalar(500.0, unit='K'))     # T0 bounds
    ]
)

# MCMC sampling
vtf.mcmc(n_samples=1000, n_walkers=32, n_burn=500, progress=True)

# Access VTF parameters
print(f"Apparent activation energy: {vtf.activation_energy}")
print(f"Preexponential factor: {vtf.preexponential_factor}")
print(f"T0 parameter: {vtf.T0}")

# Compare models using Bayesian evidence
evidence_arrhenius = arrhenius.evidence()
evidence_vtf = vtf.evidence()
bayes_factor = np.exp(evidence_vtf - evidence_arrhenius)
print(f"Bayes factor (VTF/Arrhenius): {bayes_factor}")
if bayes_factor > 10:
    print("Strong evidence for super-Arrhenius behavior")
```

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

### Create pymatgen DiffusionAnalyzer (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Initializes pymatgen's DiffusionAnalyzer using the loaded structures, a temperature of 300 K, and the previously defined parameters. This prepares the object for MSD and diffusivity calculations.

```python
pymatgen_diff = PymatgenDiffusionAnalyzer.from_structures(\n    xd.structures, temperature=300, **p_params)
```

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

### Compute Diffusion Coefficient in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_d.ipynb

Calculates self-diffusion coefficient using Bayesian posterior sampling starting from specified time. Requires kinisi and scipp; inputs: start time, random state. Outputs: Updated diff object with D and intercept distributions. Ensures reproducibility; progress disabled for simplicity.

```python
start_of_diffusion = 3000 * sc.Unit('fs')
diff.diffusion(start_of_diffusion, progress=False, random_state=rng)
```

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

### Define kinisi analysis parameters (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Sets up a dictionary with species, time step (including Scipp units), step skip (dimensionless), and progress flag for kinisi's DiffusionAnalyzer.

```python
params = {'specie': 'Li',\n          'time_step': 2.0 * sc.Unit('fs'),\n          'step_skip': 50 * sc.Unit('dimensionless'),\n          'progress': False\n          }
```

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

### Plot MSD with Error Bars on Log-Log Scale in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_d.ipynb

Plots MSD on log-log scale to identify diffusive regime, adding a vertical line at estimated start time. Depends on matplotlib and numpy; inputs from diff object. Outputs: Log-scaled plot highlighting regime change. Helps in selecting diffusion start; assumes 3000 fs threshold.

```python
fig, ax = plt.subplots()

ax.errorbar(diff.dt.values, diff.msd.values, np.sqrt(diff.msd.variances))
ax.axvline(3000, color='g')
ax.set_xlabel(f'Time / {diff.dt.unit}')
ax.set_ylabel(f'MSD / {diff.msd.unit}')
ax.set_xscale('log')
ax.set_yscale('log')
plt.show()
```

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

### Load XDATCAR file (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Instantiates a pymatgen Xdatcar object from a compressed XDATCAR file, providing structural data for diffusion analysis.

```python
xd = Xdatcar('./example_XDATCAR.gz')
```

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

### Clone Repository from GitHub

Source: https://github.com/kinisi-dev/kinisi/blob/main/CONTRIBUTING.md

Clones the forked repository to the local machine using SSH authentication. This is the first step in setting up the local development environment. Requires a GitHub account with SSH keys configured.

```shell
git clone git@github.com:your_name_here/kinisi.git
```

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

### Calculate diffusion coefficient from MSD fit

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/ase_COG.ipynb

Calculates the diffusion coefficient by fitting the MSD curve starting from the specified time (60 ps). This identifies the linear regime where Fickian diffusion occurs. The progress bar is disabled for clean output.

```python
start_of_diffusion = 60 * sc.Unit('ps')
diff.diffusion(start_of_diffusion, progress = False)
```

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

### Import libraries and set random seed (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Imports NumPy, Matplotlib, Scipp, and the DiffusionAnalyzer classes from kinisi and pymatgen. Also loads the Xdatcar utility and initializes a reproducible random number generator. Required for subsequent analysis steps.

```python
import numpy as np\nimport matplotlib.pyplot as plt\nimport scipp as sc\nfrom kinisi.analyze import DiffusionAnalyzer as KinisiDiffusionAnalyzer\nfrom pymatgen.analysis.diffusion.analyzer \\n    import DiffusionAnalyzer as PymatgenDiffusionAnalyzer\nfrom pymatgen.io.vasp import Xdatcar\nnp.random.seed(42)\nrng = np.random.RandomState(42)
```

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

### Plot Diffusion Data on Log-Log Scale

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_dj.ipynb

Creates a log-log plot of diffusion data with error bars to visualize the diffusive regime. Uses matplotlib for plotting and includes a vertical line to mark the estimated start of diffusion. Dependencies include matplotlib and numpy.

```python
fix, ax = plt.subplots()

ax.errorbar(diff.dt.values, diff.mstd.values, np.sqrt(diff.mstd.values))
ax.axvline(4000, color='g')
ax.set_xlabel(f'Time / {diff.dt.unit}')
ax.set_ylabel(f'MSTD / {diff.mstd.unit}')
ax.set_yscale('log')
ax.set_xscale('log')
plt.show()
```

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

### Plot Joint Posterior with Corner in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_d.ipynb

Imports corner library and plots joint posterior for diffusion coefficient and intercept using flatchain. Depends on corner, numpy, and kinisi; inputs from diff.flatchain. Outputs: Corner plot with labels including units. Visualizes correlations; requires corner installation.

```python
from corner import corner

corner(np.array([i.values for i in diff.flatchain.values()]).T, 
       labels=['/'.join([k, str(v.unit)]) for k, v in diff.flatchain.items()])
plt.show()
```

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

### Define pymatgen input parameters (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Creates a dictionary with species, time step, and step skip settings for use with pymatgen's DiffusionAnalyzer. These parameters match those used later for kinisi analysis.

```python
p_params = {'specie': 'Li',\n            'time_step': 2.0,\n            'step_skip': 50\n            }
```

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

### Initialize MDAnalysis Universe and Apply Cell Dimensions (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Initializes an MDAnalysis Universe from a trajectory file and applies the previously extracted cell dimensions to each time step. This ensures the simulation cell is correctly represented.

```python
from MDAnalysis.core.universe import Universe
from MDAnalysis.analysis.transformations import NoJump

u = Universe(path_to_file, 
             path_to_file, 
             format='XYZ',
             topology_format='XYZ', 
             dt=20.0/1000)
for ts, dims in zip(u.trajectory, cell_dimensions):
    ts.dimensions = dims
```

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

### Running MCMC Sampling with Emcee in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Initializes and runs an ensemble sampler using emcee from MAP estimates, discards burn-in, and scales the chain for diffusion units. Purpose: generates posterior samples. Depends on emcee and numpy; inputs: 32 walkers, 1500 steps; outputs: flatchain array; limitation: fixed walker count and steps may need tuning for convergence.

```python
pos = max_post + max_post * 1e-3 * np.random.randn(32, max_post.size)

sampler = EnsembleSampler(*pos.shape, log_posterior)
sampler.run_mcmc(pos, 1000 + 500, progress=False)
flatchain = sampler.get_chain(flat=True, discard=500)

flatchain[:, 0] /= 60000
```

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

### Import ASE and MDAnalysis for File Reading (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Imports necessary modules from ASE and MDAnalysis to facilitate reading trajectory files, particularly 'extended xyz' format, which requires assistance from ASE.

```python
from ase.io import read
from MDAnalysis import Universe
import os
```

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

### Import Libraries for Diffusion Analysis in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_d.ipynb

Imports essential libraries for data handling, plotting, and diffusion analysis from VASP files. Requires numpy, matplotlib, scipp, pymatgen, and kinisi. Initializes a random state for reproducibility. No inputs or outputs; sets up the environment.

```python
import numpy as np
import matplotlib.pyplot as plt
import scipp as sc
from pymatgen.io.vasp import Xdatcar
from kinisi.analyze import DiffusionAnalyzer
rng = np.random.RandomState(42)
```

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

### Import ufloat from uncertainties (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Loads the ufloat function to create numbers with uncertainties, used later for printing pymatgen's diffusion coefficient.

```python
from uncertainties import ufloat
```

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

### Read XDATCAR and Initialize DiffusionAnalyzer

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_msd.ipynb

Reads a VASP XDATCAR file using `pymatgen` and initializes the `DiffusionAnalyzer` from `kinisi` using the specified XDATCAR object and simulation parameters.

```python
xd = Xdatcar('./example_XDATCAR.gz')
diff = DiffusionAnalyzer.from_xdatcar(xd, **params)
```

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

### Create kinisi DiffusionAnalyzer (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Instantiates kinisi's DiffusionAnalyzer directly from the Xdatcar object using the parameters defined above. This object provides MSD data with uncertainty estimates.

```python
kinisi_diff = KinisiDiffusionAnalyzer.from_xdatcar(xd, **params)
```

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

### Import Libraries for Diffusion Analysis (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Imports core libraries for diffusion analysis, including NumPy, Scipp, Kinisi's DiffusionAnalyzer, and MDAnalysis's MSD module. It also suppresses common deprecation and runtime warnings to ensure cleaner output.

```python
import warnings

warnings.filterwarnings('ignore', category=DeprecationWarning)
warnings.filterwarnings('ignore', category=RuntimeWarning)
warnings.filterwarnings('ignore', category=UserWarning)

import numpy as np
import scipp as sc

import kinisi
from kinisi.analyze import DiffusionAnalyzer
import MDAnalysis.analysis.msd as msd
from MDAnalysis.transformations.nojump import NoJump
```

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

### Initialize DiffusionAnalyzer from ASE trajectory

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/ase_COG.ipynb

Creates a DiffusionAnalyzer instance using the from_ase class method. This processes the loaded trajectory with the specified parameters to prepare for mean-squared displacement calculation.

```python
diff = DiffusionAnalyzer.from_ase(traj, **params)
```

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

### Commit and Push Changes to GitHub

Source: https://github.com/kinisi-dev/kinisi/blob/main/CONTRIBUTING.md

Stages all modified files, creates a commit with a descriptive message, and pushes the branch to the remote GitHub repository. Prepares the changes for pull request submission. Requires Git authentication to be properly configured.

```shell
git add .
git commit -m "Your detailed description of your changes."
git push origin name-of-your-bugfix-or-feature
```

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

### Import libraries and set random seed for jump diffusion analysis (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_dj.ipynb

Loads NumPy, Matplotlib, Scipp, Kinisi, and Pymatgen modules required for diffusion analysis. Sets a fixed random seed for reproducibility of any stochastic processes. No inputs; prepares the environment for subsequent steps.

```python
import numpy as np
import matplotlib.pyplot as plt
import scipp as sc
from kinisi.analyze import JumpDiffusionAnalyzer
from pymatgen.io.vasp import Xdatcar
np.random.seed(42)
rng = np.random.RandomState(42)
```

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

### Define Parameters for DiffusionAnalyzer in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_d.ipynb

Sets up a dictionary with simulation parameters like species, time step, step skip, and progress flag for the DiffusionAnalyzer. Adds dimension key to restrict to xy-plane. Inputs are simulation details; outputs a params dict used in analysis initialization. Limited to specified units and no heavy dependencies beyond scipp.

```python
params = {'specie': 'Li',
          'time_step': 2.0 * sc.Unit('fs'),
          'step_skip': 50 * sc.Unit('dimensionless'),
          'progress': False
          }
params['dimension']= 'xy'
```

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

### Load XDATCAR file and compute jump diffusion analyzer (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_dj.ipynb

Reads a compressed XDATCAR file using Pymatgen, then creates a JumpDiffusionAnalyzer instance with the previously defined parameters. The analyzer calculates mean‑squared total displacement and related statistics. Outputs are stored in the 'diff' object.

```python
xd = Xdatcar('./example_XDATCAR.gz')
diff = JumpDiffusionAnalyzer.from_xdatcar(xd, **params)
```

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

### Import Python libraries for analysis

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Imports essential Python libraries including NumPy for array operations, Matplotlib for visualization, and SciPy for statistical functions.

```python
import numpy as np
import matplotlib.pyplot as plt
from scipy.stats import multivariate_normal
from scipy.optimize import minimize
from emcee import EnsembleSampler
from corner import corner
```

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

### Execute Code Formatting and Test Suite

Source: https://github.com/kinisi-dev/kinisi/blob/main/CONTRIBUTING.md

Runs pre-commit hooks to automatically format code and check for quality issues, then executes the complete pytest test suite. Both commands must pass before changes can be committed. Ensures code consistency and prevents regressions.

```shell
pre-commit run --all-files
pytest
```

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

### Load displacement data in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Loads precomputed atomic displacement data from a NumPy .npz file and prints the array shape for verification.

```python
displacements = np.load('_static/displacements.npz')['disp']

print('Displacements shape', displacements.shape)
```

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

### Plot MSD over time in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Loads and visualizes mean-squared displacement data across different timesteps, showing the diffusion relationship.

```python
dt, msd = np.loadtxt('_static/msd.txt')

plt.plot(dt, msd, c='#0173B2')
plt.ylabel('MSD/Å$^2$')
plt.xlabel(r'$\Delta t$/ps')
plt.xlim(0, None)
plt.ylim(0, None)
plt.show()
```

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

### Import libraries for diffusion analysis with Kinisi

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/ase_COG.ipynb

Imports required Python libraries including NumPy for numerical operations, ASE for trajectory I/O, Matplotlib for visualization, Kinisi for diffusion analysis, and Scipp for unit handling and array operations.

```python
import numpy as np
from ase.io import read
import matplotlib.pyplot as plt
from kinisi.analyze import DiffusionAnalyzer
import scipp as sc
```

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

### Import Libraries for MSD Analysis

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_msd.ipynb

Imports necessary Python libraries for data analysis and visualization, including `scipp`, `numpy`, `matplotlib`, `pymatgen`, and `kinisi`.

```python
import scipp as sc
import numpy as np
import matplotlib.pyplot as plt
from pymatgen.io.vasp import Xdatcar
from kinisi.analyze import DiffusionAnalyzer
```

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

### Import Libraries and Set Up Warnings - Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/arrhenius_t.ipynb

Imports necessary libraries for data analysis, simulation, and visualization. It also configures warning filters to suppress specific user and runtime warnings, ensuring cleaner output during documentation generation.

```python
import numpy as np
import scipp as sc
import MDAnalysis as mda
import matplotlib.pyplot as plt
from kinisi.analyze import DiffusionAnalyzer
from kinisi.arrhenius import Arrhenius
import warnings
np.random.seed(42)
warnings.filterwarnings("ignore", category=UserWarning)
warnings.filterwarnings("ignore", category=RuntimeWarning)
```

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

### Access MCMC Samples using Kinisi DiffusionAnalyzer (Python)

Source: https://context7.com/kinisi-dev/kinisi/llms.txt

This snippet demonstrates how to use the `DiffusionAnalyzer` from the `kinisi` library to perform MCMC sampling and access the resulting gradient and intercept samples. It also shows how to calculate custom statistics like the median and credible intervals, and access the `flatchain` for plotting. Dependencies include `kinisi`, `scipp`, and `numpy`.

```python
from kinisi.diffusion_analyzer import DiffusionAnalyzer
import scipp as sc
import numpy as np

analyzer = DiffusionAnalyzer.from_xdatcar(
    trajectory=xdatcar,
    specie='Li',
    time_step=sc.scalar(2.0, unit='fs'),
    step_skip=sc.scalar(100.0),
    progress=True
)

analyzer.diffusion(
    start_dt=sc.scalar(10.0, unit='ps'),
    n_samples=1000,
    n_walkers=32,
    progress=True
)

# Access MCMC samples
gradient_samples = analyzer.diff.gradient.values  # Array of gradient samples
intercept_samples = analyzer.diff.intercept.values if analyzer.intercept else None

# Calculate custom statistics
median_gradient = np.median(gradient_samples)
percentile_68 = np.percentile(gradient_samples, [16, 84])

print(f"Median gradient: {median_gradient}")
print(f"68% credible interval: {percentile_68}")

# Access flatchain for plotting
flatchain = analyzer.flatchain
print(f"Flatchain keys: {list(flatchain.keys())}")
```

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

### Plot MSD comparison between pymatgen and kinisi (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Generates a Matplotlib figure showing the mean‑squared displacement curves from both libraries for visual verification of agreement.

```python
fig, ax = plt.subplots()\n\nax.plot(pymatgen_diff.dt, pymatgen_diff.msd, label='pymatgen')\nax.plot(kinisi_diff.dt.values, kinisi_diff.msd.values, label='kinisi')\nax.legend()\nax.set_xlabel(f'Time / {kinisi_diff.dt.unit}')\nax.set_ylabel(f'MSD / {kinisi_diff.msd.unit}')\nax.set_xlim(0, None)\nax.set_ylim(0, None)\nplt.show()
```

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

### Calculate MSD using Kinisi from Universe (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Calculates MSD using the Kinisi library, initializing from an MDAnalysis Universe. It utilizes custom time step parameters and a scipp array for time intervals to compute the MSD.

```python
import scipp as sc
from kinisi import DiffusionAnalyzer

params = {'specie': 'LI',
          'time_step': 0.001 * sc.Unit('ps'),
          'step_skip': 20 * sc.units.dimensionless,
          'progress': False,
          'dt': sc.arange(dim='time interval', start=0.1 * sc.Unit('ps'),
                         stop=4.1 * sc.Unit('ps'),
                         step=0.1 * sc.Unit('ps'))
          }

kinisi_from_universe = DiffusionAnalyzer.from_universe(u, **params)
kinisi_MSD = kinisi_from_universe.msd
time = kinisi_from_universe.dt
```

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

### Print pymatgen diffusion coefficient with uncertainty (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Displays the diffusion coefficient calculated by pymatgen together with its standard deviation using the uncertainties package.

```python
print('D from pymatgen:', \n      ufloat(pymatgen_diff.diffusivity, pymatgen_diff.diffusivity_std_dev))
```

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

### Visualize displacement distribution in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Creates a histogram of atomic displacements using Matplotlib, showing the probability distribution of particle movements.

```python
plt.hist(displacements.flatten(), bins=50, 
         density=True, color='#0173B2')
plt.xlabel(r'$\mathbf{x}(5\;\mathrm{ps})$/Å')
plt.ylabel(r'$p[\mathbf{x}(5\;\mathrm{ps})]$Å$^{-1}$')
plt.xlim(-6, 6)
plt.show()
```

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

### Combine multiple trajectory files for analysis

Source: https://context7.com/kinisi-dev/kinisi/llms.txt

Loads and combines multiple trajectory files for improved statistical analysis. Supports consecutive trajectories that continue from each other or identical independent runs. Requires XDATCAR files and scipp library.

```python
from pymatgen.io.vasp.outputs import Xdatcar
from kinisi.diffusion_analyzer import DiffusionAnalyzer
import scipp as sc

# Load multiple XDATCAR files
trajectories = [
    Xdatcar('run1/XDATCAR'),
    Xdatcar('run2/XDATCAR'),
    Xdatcar('run3/XDATCAR')
]

# Consecutive: trajectories continue from each other
analyzer = DiffusionAnalyzer.from_xdatcar(
    trajectory=trajectories,
    specie='Li',
    time_step=sc.scalar(2.0, unit='fs'),
    step_skip=sc.scalar(100.0),
    dtype='consecutive',    # Trajectories are consecutive
    progress=True
)

# Or use 'identical' for independent runs from same initial conditions
analyzer_identical = DiffusionAnalyzer.from_xdatcar(
    trajectory=trajectories,
    specie='Li',
    time_step=sc.scalar(2.0, unit='fs'),
    step_skip=sc.scalar(100.0),
    dtype='identical',      # Independent runs
    progress=True
)

analyzer.diffusion(start_dt=sc.scalar(10.0, unit='ps'), progress=True)
print(f"Combined diffusion: {analyzer.D}")
```

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

### Load DL_POLY trajectory using ASE

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/ase_COG.ipynb

Reads a compressed DL_POLY HISTORY file containing molecular dynamics simulation data for ethene in ZSM-5 zeolite. The trajectory is loaded into memory with all frames using ASE's read function with format specification.

```python
traj = read('ethene_zeo_HISTORY.gz', format='dlp-history', index=':')
```

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

### Initialize Multivariate Normal Distribution Object

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Creates a `scipy.stats.multivariate_normal` object using the calculated mean MSD values and the covariance matrix. This object can be used to simulate trajectories.

```python
gp = multivariate_normal(mean=msd, cov=cov, allow_singular=True)
```

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

### Define Temperatures and Initialize Diffusion Dictionary - Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/arrhenius_t.ipynb

Sets up an array of temperatures for simulations and initializes a dictionary to store the mean and variance of the diffusion coefficient at each temperature.

```python
temperatures = np.array([500, 600, 700, 800])
D = {'mean': [], 'var': []}
```

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

### Visualizing Posterior with Corner Plot in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Creates a corner plot of diffusion coefficient and offset samples. Purpose: explores parameter posteriors. Depends on corner and matplotlib; inputs: flatchain; outputs: plot; limitation: requires predefined labels and units.

```python
corner(flatchain,
       labels=['$D$/cm$^2$s$^{-1}$', r'$D_{\mathrm{offset}}$/Å$^2$'])
plt.show()
```

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

### Plot kinisi MSD with error bars (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Creates a plot of kinisi's MSD values including uncertainties as error bars, demonstrating kinisi's capability to provide variance information.

```python
fig, ax = plt.subplots()\n\nax.errorbar(kinisi_diff.dt.values, \n            kinisi_diff.msd.values, \n            np.sqrt(kinisi_diff.msd.variances), \n            c='#ff7f0e')\nax.set_xlabel(f'Time / {kinisi_diff.dt.unit}')\nax.set_ylabel(f'MSD / {kinisi_diff.msd.unit}')\nax.set_xlim(0, None)\nax.set_ylim(0, None)\nplt.show()
```

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

### Access kinisi diffusion coefficient (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/pymatgen.ipynb

Retrieves the diffusion coefficient (with uncertainty) directly from the kinisi DiffusionAnalyzer object.

```python
kinisi_diff.D
```

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

### Plotting MSD with Credible Intervals (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Plots the MSD from Kinisi along with credible intervals derived from the diffusion analysis distributions. This provides a more comprehensive view of the uncertainty in the MSD.

```python
credible_intervals = [[16, 84], [2.5, 97.5], [0.15, 99.85]]
alpha = [0.6, 0.4, 0.2]

plt.plot(kinisi_from_universe.dt, kinisi_from_universe.msd, 'k-')
for i, ci in enumerate(credible_intervals):
    plt.fill_between(kinisi_from_universe.dt.values,
                     *np.percentile(kinisi_from_universe.distributions, 
                                    ci, 
                                    axis=1),
                     alpha=alpha[i],
                     color='#0173B2',
                     lw=0)
plt.ylabel('MSD/Å$^2$')
plt.xlabel(r'$Delta t$/ps')
plt.show()
```

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

### Analyze Diffusion with Kinisi and Visualize MSD

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/condition_number.ipynb

This snippet sets up and analyzes diffusion data using Kinisi's DiffusionAnalyzer. It reads molecular dynamics trajectory data, configures analysis parameters, calculates diffusion coefficients, and visualizes the Mean Squared Displacement (MSD) plot with credible intervals. Dependencies include numpy, scipp, kinisi, ase, MDAnalysis, and matplotlib.

```python
import os
import numpy as np
import scipp as sc
import kinisi
from kinisi.analyze import DiffusionAnalyzer
from ase.io import read
from MDAnalysis import Universe
import matplotlib.pyplot as plt

credible_intervals = [[16, 84], [2.5, 97.5], [0.15, 99.85]]
alpha = [0.6, 0.4, 0.2]

path_to_file = os.path.join(os.path.dirname(kinisi.__file__), 
                            'tests/inputs/LiPS.exyz')
atoms = read(path_to_file, format='extxyz', index=':')

cell_dimensions = []
for frame in atoms:
    lengths = frame.cell.lengths()
    angles = frame.cell.angles()
    cell = [*lengths, *angles]
    cell_dimensions.append(cell)

u = Universe(path_to_file, 
             path_to_file, 
             format='XYZ', 
             topology_format='XYZ', 
             dt=20.0/1000)
for ts, dims in zip(u.trajectory, cell_dimensions):
    ts.dimensions = dims

params = {'specie': 'LI',
          'time_step': 0.001 * sc.Unit('ps'),
          'step_skip': 20 * sc.units.dimensionless,
          'progress': False
          }

diff = DiffusionAnalyzer.from_universe(u, **params)
diff.diffusion(1.5 * sc.Unit('ps'))

fig, ax = plt.subplots()
ax.plot(diff.dt.values, diff.msd.values, 'k-')
for i, ci in enumerate(credible_intervals):
    ax.fill_between(diff.dt.values,
                      *np.percentile(diff.distributions, ci, axis=1),
                      alpha=alpha[i],
                      color='#0173B2',
                      lw=0)
ax.set_xlabel(f'Time / {diff.dt.unit}')
ax.set_ylabel(f'MSD / {diff.msd.unit}')
ax.set_xlim(0, None)
ax.set_ylim(0, None)
plt.show()
```

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

### Calculate squared displacements in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Computes squared displacements across all dimensions and visualizes their distribution, a key step in mean-squared displacement analysis.

```python
sq_displacements = np.sum(displacements ** 2, 
                          axis=2).flatten()

plt.hist(sq_displacements, bins=50, 
         density=True, color='#0173B2')
plt.xlabel(r'$\mathbf{s}^2$/Å$^2$')
plt.ylabel(r'$p(\mathbf{s}^2)$/Å$^{-2}$')
plt.show()
```

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

### Initialize Arrhenius Object with Bounds - Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/arrhenius_t.ipynb

Creates an Arrhenius object using the prepared scipp.DataArray. It specifies bounds for the activation energy and preexponential factor, constraining the fitting process.

```python
s = Arrhenius(td, bounds=[[0.1 * sc.Unit('eV'), 0.2 * sc.Unit('eV')], 
                          [1e-5 * td.data.unit, 1e-4 * td.data.unit]])
```

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

### Histogram of Diffusion Coefficients (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Generates a histogram of the calculated diffusion coefficients. This visualization helps in understanding the distribution and spread of the diffusion coefficient values.

```python
plt.hist(kinisi_from_universe.D.values)
```

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

### Accessing Diffusion Analysis Results (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Retrieves the diffusion analysis results from the Kinisi object. This attribute holds detailed information about the diffusion analysis performed.

```python
kinisi_from_universe.da
```

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

### Define molecule parameters for COM diffusion analysis

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/ase_COG.ipynb

Configures parameters for analyzing center of mass diffusion of two ethene molecules. Defines atom indices for each molecule and atomic masses. Creates scipp arrays with proper dimensions ('particle' for molecules, 'atoms in particle' for constituent atoms) and sets time step and sampling parameters. Supports only identical molecules.

```python
molecules = [[288, 289, 290, 291, 292, 293],
             [284, 295, 296, 297, 298, 299]]
mass    =  [12, 12, 1.008, 1.008, 1.008, 1.008]

params = {'specie': None,
           'time_step': 1.2e-03 * sc.Unit('ps'),
           'step_skip': 100 * sc.Unit('dimensionless'),
           'specie_indices': sc.array(dims=['particle', 'atoms in particle'], 
                                      values=molecules, 
                                      unit=sc.Unit('dimensionless')),
           'masses': sc.array(dims = ['atoms in particle'], 
                              values = mass),
           'progress': False
           }
```

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

### Configure Simulation Parameters for MSD Calculation

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_msd.ipynb

Defines a dictionary of parameters required by `DiffusionAnalyzer`. This includes the atomic species, simulation time step with units, data writing frequency (step skip), and an option for progress meter.

```python
params = {'specie': 'Li',
          'time_step': 2.0 * sc.Unit('fs'),
          'step_skip': 50 * sc.Unit('dimensionless'),
          'progress': False
          }
```

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

### Calculate mean-squared displacement in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Computes and visualizes the mean of squared displacements, marking the result on the distribution plot for comparison.

```python
msd = np.mean(sq_displacements)

print(f'MSD = {msd:.3f} Å$^2$')

plt.hist(sq_displacements, bins=50, 
         density=True, color='#0173B2')
plt.axvline(msd, color='k')
plt.xlabel(r'$\mathbf{s}^2$/Å$^2$')
plt.ylabel(r'$p(\mathbf{s}^2)$/Å$^{-2}$')
plt.show()
```

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

### Calculate MSD using MDAnalysis (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Performs Mean Squared Displacement (MSD) calculation using MDAnalysis. It includes unwrapping the trajectory, setting up the EinsteinMSD analysis, running the calculation, and extracting the results and time series.

```python
import MDAnalysis.analysis.msd as msd
import numpy as np

u.trajectory.add_transformations(NoJump())
MSD = msd.EinsteinMSD(u, 
                      select='type LI', 
                      msd_type='xyz', 
                      fft=True, 
                      verbose=False)
MSD.run(verbose=False)

mda_MSD = MSD.results.timeseries
mda_dt = np.linspace(u.trajectory.dt, 
                     u.trajectory.dt * len(mda_MSD), 
                     len(mda_MSD))
```

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

### Analyze Molecular Centers of Mass (Python)

Source: https://context7.com/kinisi-dev/kinisi/llms.txt

This Python code demonstrates calculating diffusion for molecular species by computing centers of mass using Kinisi. It depends on Kinisi and Scipp, requiring universe data and molecule indices as input to perform analysis. Outputs diffusion for molecules like water, but the snippet is incomplete as provided.

```python
from kinisi.diffusion_analyzer import DiffusionAnalyzer
import scipp as sc

# Define molecule indices (e.g., water molecules with 3 atoms each)
```

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

### Plotting MSD Comparison (Python)

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/mdanalysis.ipynb

Generates a plot comparing the MSD results obtained from Kinisi and MDAnalysis. This visualization helps in assessing the agreement between the two methods.

```python
import matplotlib.pyplot as plt

plt.plot(time, kinisi_MSD, label='Kinisi MSD', c='#ff7f0e')
plt.plot(mda_dt, mda_MSD, label='MDanalysis', ls='--')
plt.ylabel('MSD (Å$^2$)')
plt.xlabel('Diffusion time (ps)')
plt.legend()

plt.show()
```

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

### Parse Trajectories with MDAnalysis (Python)

Source: https://context7.com/kinisi-dev/kinisi/llms.txt

This Python code uses MDAnalysis to load GROMACS or other supported trajectory formats and computes sodium diffusion coefficients using Kinisi's DiffusionAnalyzer. It requires MDAnalysis, Kinisi, and Scipp libraries, taking topology and trajectory files as input to output diffusion coefficients with uncertainty after sampling. Note that progress indicators can be disabled for non-interactive environments.

```python
import MDAnalysis as mda
from kinisi.diffusion_analyzer import DiffusionAnalyzer
import scipp as sc

# Load trajectory with MDAnalysis
universe = mda.Universe('topology.pdb', 'trajectory.xtc')

# Analyze diffusion
analyzer = DiffusionAnalyzer.from_universe(
    trajectory=universe,
    specie='NA',                            # Sodium atoms
    time_step=sc.scalar(2.0, unit='fs'),
    step_skip=sc.scalar(50.0),
    dimension='xyz',
    distance_unit=sc.units.angstrom,
    progress=True
)

analyzer.diffusion(
    start_dt=sc.scalar(5.0, unit='ps'),
    n_samples=1000,
    n_walkers=32,
    progress=True
)

print(f"Sodium diffusion: {analyzer.D}")
```

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

### Run Specific Test Module with pytest

Source: https://github.com/kinisi-dev/kinisi/blob/main/CONTRIBUTING.md

Executes tests for a specific module file, allowing focused testing during development. This is faster than running the full test suite and is useful when working on specific components. Accepts any valid test file path.

```shell
pytest kinisi/test_analyze.py
```

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

### Parse Trajectories with ASE (Python)

Source: https://context7.com/kinisi-dev/kinisi/llms.txt

This Python snippet loads ASE-compatible trajectory files to analyze lithium diffusion using Kinisi. It depends on ASE, Kinisi, and Scipp, processing trajectory data to estimate diffusion coefficients via MCMC sampling. Outputs include the diffusion coefficient, and it assumes the trajectory contains the required atomic species.

```python
from ase.io.trajectory import Trajectory
from kinisi.diffusion_analyzer import DiffusionAnalyzer
import scipp as sc

# Load ASE trajectory
traj = Trajectory('simulation.traj')

# Analyze diffusion
analyzer = DiffusionAnalyzer.from_ase(
    trajectory=traj,
    specie='Li',
    time_step=sc.scalar(1.0, unit='fs'),
    step_skip=sc.scalar(10.0),
    dimension='xyz',
    distance_unit=sc.units.angstrom,
    progress=True
)

analyzer.diffusion(
    start_dt=sc.scalar(2.0, unit='ps'),
    n_samples=500,
    n_walkers=24,
    progress=True
)

print(f"Diffusion coefficient: {analyzer.D}")
```

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

### Save and Load Diffusion Analysis Data

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/vasp_dj.ipynb

Provides methods to save the jump diffusion analysis object to HDF5 format and reload it later. The HDF5 format ensures efficient storage of the analysis results and metadata. Dependencies include h5py for file handling.

```python
!rm example.hdf
```

```python
diff.to_hdf5('example.hdf')
```

```python
loaded_diff = JumpDiffusionAnalyzer.from_hdf5('example.hdf')
```

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

### Computing Maximum A Posteriori Estimate in Python

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

This snippet defines a negative log-posterior for minimization to find MAP values of slope and intercept. Purpose: provides initial positions for MCMC. Depends on scipy.optimize.minimize; inputs: initial guess [1, 0]; outputs: optimized theta array; no major limitations noted.

```python
def nll(*args) -> float:
    """
    General purpose negative log-posterior.

    :return: Negative log-posterior
    """
    return -log_posterior(*args)

max_post = minimize(nll, [1, 0]).x
```

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

### Load and Plot Covariance Matrix

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Loads a pre-computed covariance matrix from a .npz file and visualizes it as a contour plot. It uses NumPy for loading data and Matplotlib for generating the contour plot with appropriate labels and a color bar.

```python
data = np.load('_static/cov.npz')
cov = data['cov']

plt.subplots(figsize=(6, 4.9))
plt.contourf(*np.meshgrid(dt, dt), cov, levels=20)
plt.xlabel(r'$Delta t_n$/ps')
plt.ylabel(r'$Delta t_{n+m}$/ps')
plt.axis('equal')
plt.colorbar(label=r'$mathrm{cov}' + 
             r'(langle mathbf{s}^2(Delta t_n) 
angle, ' + 
             r'langle mathbf{s}^2(Delta t_{n+m}) 
angle)$')
plt.show()
```

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

### Calculate and Display Mean MSD with Standard Deviation

Source: https://github.com/kinisi-dev/kinisi/blob/main/docs/source/methodology.ipynb

Calculates the mean of squared displacements and its standard deviation (derived from the previously calculated variance), then prints the result in a formatted string. It utilizes NumPy for mean and square root calculations.

```python
print(rf'MSD = {np.mean(sq_displacements):.3f}+\-{np.sqrt(var):.3f} Å^2')
```