Metadata-Version: 2.4
Name: magic-3-tools
Version: 0.2.0
Summary: A library for MagiC 3 output analysis and RDF calculations
Author-email: Alexander Lyubartsev <alexander.lyubartsev@su.se>
License-Expression: GPL-3.0-only
Project-URL: Homepage, https://bitbucket.org/magic-su/magic-3/src/master/
Project-URL: Repository, https://bitbucket.org/magic-su/magic-3
Project-URL: Issues, https://bitbucket.org/magic-su/magic-3/issues
Keywords: molecular dynamics,RDF,radial distribution function,chemistry,physics
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: matplotlib>=3.7.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Provides-Extra: trajectory
Requires-Dist: mdtraj>=1.9.0; extra == "trajectory"
Dynamic: license-file

# MagicTools

Python library and CLI tools for analysis of [MagiC-3](https://bitbucket.org/magic-su/magic-3) molecular dynamics simulations.

[![PyPI version](https://img.shields.io/pypi/v/magic-3-tools.svg)](https://pypi.org/project/magic-3-tools/)
[![Python](https://img.shields.io/pypi/pyversions/magic-3-tools.svg)](https://pypi.org/project/magic-3-tools/)
[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

## Features

- **Radial Distribution Functions (RDF)**: Calculate and analyze pair distribution functions
- **Angular Distribution Functions (ADF)**: Analyze angular correlations
- **Molecular System Manipulation**: Build and modify molecular systems
- **Trajectory Processing**: Read and process molecular dynamics trajectories
- **Visualization**: Plot distribution functions with customizable settings

## Installation

### From PyPI (recommended)

```bash
pip install magic-3-tools
```

### From source (as part of MagiC-3 repository)

```bash
git clone https://bitbucket.org/magic-su/magic-3.git
cd magic-3/MagicTools
pip install .
```

For development (editable install):

```bash
pip install -e ".[dev]"
```

## Usage

### Python library

```python
import MagicTools
print(MagicTools.__version__)
```

Import specific classes and functions:

```python
from MagicTools import System, OnePlot, MultPlot, RDFCalculator
```

Read MagiC-format files:

```python
from MagicTools.MagicTools import ReadMagiC

system = ReadMagiC("system.magic")
for mol_type in system.MolTypes:
    print(mol_type.Name, mol_type.NMol)
```

Plot distribution functions:

```python
OnePlot(system.DFs[0])
MultPlot(system.DFs)
```

### CLI tool: `magic-rdf`

The `magic-rdf` command calculates Radial Distribution Functions from MagiC-3 trajectories.

> **Note:** If you installed MagiC-3 from source using the main `install.sh`, the same tool is
> available as `rdf.py` (a symlink in `$MAGIC/bin`). Both names run the same code.
> The User Guide uses the `rdf.py` convention.

**Basic usage:**

```bash
magic-rdf
```

By default, `magic-rdf` reads input from `rdf.inp` in the current directory.

**Options:**

```text
magic-rdf [-i input_file] [-np N] [--force] [--opt_memory_use]

  -i input_file     Input file name (default: rdf.inp)
  -np N             Run in parallel using N CPU cores
  --force           Skip trajectory format check
  --opt_memory_use  Optimize memory usage (useful for large trajectories)
```

**Example:**

```bash
# Use default input file (rdf.inp)
magic-rdf

# Specify custom input file
magic-rdf -i my_calculation.inp

# Run parallel RDF calculation on 4 cores
magic-rdf -i rdf.inp -np 4
```

The input file uses MagiC-2 RDF format (with `&PARAMETERS` section). Errors and debug output are written to `rdf.err`.

### Optional dependency: trajectory support

For reading external trajectory formats (e.g., from GROMACS or LAMMPS via MDTraj):

```bash
pip install "magic-3-tools[trajectory]"
```

## Requirements

- Python >= 3.10
- numpy >= 1.20
- pandas >= 1.3
- matplotlib >= 3.3

## License

This project is licensed under the GNU General Public License v3 — see [LICENSE](LICENSE) for details.

## Authors

- **Prof. Alexander Lyubartsev** (<alexander.lyubartsev@su.se>) — Principal investigator and method developer

## Citation

If you use MagicTools or MagiC-3 in your research, please cite:

- A. Mirzoev, A.P. Lyubartsev, *"MagiC: Software Package for Multiscale Modeling"*,
  J. Chem. Theory Comput. **9**(3), 1512–1520 (2013).
  [DOI: 10.1021/ct301019v](http://pubs.acs.org/doi/abs/10.1021/ct301019v)

- A. Mirzoev, L. Nordenskiöld, A.P. Lyubartsev, *"Magic v.3: An integrated software package for systematic structure-based coarse-graining"*,
  Comput. Phys. Commun. **237**, 263–273 (2019).
  [DOI: 10.1016/j.cpc.2018.11.018](https://www.sciencedirect.com/science/article/pii/S0010465518304107)

## Links

- [MagiC-3 repository](https://bitbucket.org/magic-su/magic-3)
- [Tutorials](https://bitbucket.org/magic-su/magic_tutorials)
- [Issue tracker](https://bitbucket.org/magic-su/magic-3/issues)
- [PyPI package](https://pypi.org/project/magic-3-tools/)
