<div align="center">
  <img src=https://raw.githubusercontent.com/Atomic-Samplers/quansino/refs/heads/main/docs/images/quansino_logo.png width="500"><br>
</div>

<div align="center">
  <h1><code>quansino</code> 🎲</h1>
  <p><i>Modular Stochastic Simulations for Atomistic Modelling</i></p>
</div>

***

[![PyPI version](https://badge.fury.io/py/quansino.svg)](https://badge.fury.io/py/quansino)
![Python Version](https://img.shields.io/pypi/pyversions/quansino)
[![codecov](https://codecov.io/gh/Atomic-Samplers/quansino/branch/main/graph/badge.svg?token=A864UNYUOG)](https://codecov.io/gh/Atomic-Samplers/quansino)
[![GitHub license](https://img.shields.io/github/license/Atomic-Samplers/quansino)](https://github.com/Atomic-Samplers/quansino/blob/main/LICENSE.md)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/pre-commit/pre-commit)

`quansino` is a modern simulation framework based on the Atomic Simulation Environment (ASE) designed for both material science and molecular systems. It combines the reliability of established Monte Carlo and general sampling methods with an intuitive, and flexible Python interface.

## Key Features 🎰

- Perform (grand) canonical, isobaric, and other ensemble simulations. The framework allows designing custom ensembles and custom parametrization for subsystems or degrees of freedom.
- Include algorithm for efficient sampling of complex energy landscapes, such as basin-hopping, and force-biased Monte Carlo.
- Being based on ASE, `quansino` supports a wide range of DFT codes and force fields.

## Documentation 🎱

The full documentation can be found [here](https://atomic-samplers.github.io/quansino/), and includes detailed instructions about:

- 🔧 [Installation](https://atomic-samplers.github.io/quansino/installation/install.html)
- 📖 [Overview](https://atomic-samplers.github.io/quansino/documentation/overview.html)
- 💡 [Examples](https://atomic-samplers.github.io/quansino/documentation/examples.html)

## License 🃏

This project is licensed under the terms of the BSD 3-Clause license.
