Metadata-Version: 2.4
Name: vitrum
Version: 1.0.0
Summary: vitrum is a package for generating input data and analyzing simulation data of glass structures
Author-email: Rasmus Christensen <rasmus.christensen.a1@tohoku.ac.jp>
License: MIT
Project-URL: Homepage, https://github.com/R-Chr/vitrum
Project-URL: Repository, https://github.com/R-Chr/vitrum
Project-URL: Documentation, https://vitrum.readthedocs.io/en/latest/
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: ase
Requires-Dist: pandas
Requires-Dist: scikit-learn
Requires-Dist: scipy
Requires-Dist: pymatgen
Requires-Dist: ruamel-yaml==0.17.9
Requires-Dist: numba
Requires-Dist: matplotlib
Provides-Extra: workflows
Requires-Dist: fireworks; extra == "workflows"
Requires-Dist: jobflow; extra == "workflows"
Requires-Dist: atomate2; extra == "workflows"
Provides-Extra: volume-estimation
Requires-Dist: atomate2; extra == "volume-estimation"
Requires-Dist: mp_api; extra == "volume-estimation"
Provides-Extra: persistent-homology
Requires-Dist: dionysus; extra == "persistent-homology"
Dynamic: license-file

# ⚗️ vitrum

**vitrum** is a Python package designed for the generation, analysis, and simulation of disordered and glassy atomic structures. It provides a comprehensive suite of tools for structural characterization, diffusion analysis, and tools for machine learning-driven potential development.

## 🚧 Active development
vitrum is under active development. As of 1.0, the public API follows [semantic versioning](https://semver.org/) — breaking changes will be reflected in a major version bump and noted in the [changelog](CHANGELOG.md).

## 📖 Documentation
Please see the `docs` folder for detailed documentation or check the [online documentation](https://vitrum.readthedocs.io/en/latest/).

## 📦 Installation

To install `vitrum`, you can clone the repository and install it in editable mode:

```bash
git clone https://github.com/R-Chr/vitrum.git
cd vitrum
pip install -e .
```

To install dependencies for simulation workflows (atomate2, fireworks, jobflow):

```bash
pip install -e .[workflows]
```

## 🚀 Examples
See the [`examples`](examples/) folder for runnable Jupyter notebooks demonstrating scattering/RDF analysis, Qn speciation, and random structure generation, among others.

## 🎯 Scope and Functionality

`vitrum` offers:

### 1. Structural Characterization
*   **Scattering Functions**: Calculate partial and total Radial Distribution Functions (RDF) and Structure Factors ($S(q)$) for both Neutron and X-ray scattering (`vitrum.scattering`).
*   **Ring Analysis**: Analyze ring size distributions and statistics in network glasses (`vitrum.rings`).
*   **Topological Analysis**: Compute persistent homology to identify medium-range order and topological features (`vitrum.persistent_homology`).
*   **Coordination & Angles**: Analyze bond angle distributions and coordination environments (`vitrum.coordination`).

### 2. Dynamics & Diffusion
*   **Diffusion Analysis**: Calculate Mean Squared Displacement (MSD), diffusion coefficients, and Van Hove correlation functions (`vitrum.diffusion`).

### 3. Machine Learning & Workflows
*   **BALACE Framework**: A Batch Active Learning framework for Atomistic Simulations (`vitrum.batch_active`) (requires `workflows` dependencies).
    *   Automated workflow for training Machine Learning Interatomic Potentials (MLIPs) based on ACE .
    *   Integration with VASP and LAMMPS for data generation and active learning loops.
    *   Job management via Fireworks and Jobflow.


## 👥 Author
Rasmus Christensen (rasmusc@bio.aau.dk)

## ⭐ Acknowledgements
`vitrum` relies on several powerful open-source packages:
*   [ASE](https://wiki.fysik.dtu.dk/ase/)
*   [Pymatgen](https://pymatgen.org/)
*   [NumPy](https://numpy.org/) / [SciPy](https://scipy.org/) / [pandas](https://pandas.pydata.org/)
*   [scikit-learn](https://scikit-learn.org/)
*   [Dionysus](https://mrzv.org/software/dionysus2/) / [DioDe](https://github.com/mrzv/diode)
*   [Atomate2](https://github.com/materialsproject/atomate2) / [Jobflow](https://materialsproject.github.io/jobflow/) / [Fireworks](https://materialsproject.github.io/fireworks/)
