magic-3-tools 0.2.0

A library for MagiC 3 output analysis and RDF calculations

MagicTools

Python library and CLI tools for analysis of MagiC-3 molecular dynamics simulations.

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)

pip install magic-3-tools

From source (as part of MagiC-3 repository)

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

For development (editable install):

pip install -e ".[dev]"

Usage

Python library

import MagicTools
print(MagicTools.__version__)

Import specific classes and functions:

from MagicTools import System, OnePlot, MultPlot, RDFCalculator

Read MagiC-format files:

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:

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:

magic-rdf

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

Options:

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:

# 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):

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 for details.

Authors

• Prof. Alexander Lyubartsev ([e-mail]) — 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

• 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

Links

• MagiC-3 repository
• Tutorials
• Issue tracker
• PyPI package