Metadata-Version: 2.4
Name: mimicpy
Version: 0.3.0
Summary: Companion library to the MiMiC framework for input preparation.
Home-page: https://gitlab.com/mimic-project/mimicpy
Author: Bharath Raghavan, Florian K. Schackert, Sachin Shivakumar
Author-email: b.raghavan@fz-juelich.de
License: GNU Lesser General Public License v3 or later (LGPLv3+)
Project-URL: Issues, https://gitlab.com/mimic-project/mimicpy/issues
Project-URL: User Support, https://gitlab.com/mimic-project/user-support
Project-URL: Documentation, https://mimic-project.org/
Platform: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.5,<3.12
Description-Content-Type: text/markdown
License-File: COPYING
License-File: COPYING.LESSER
Requires-Dist: numpy>=1.12.0
Requires-Dist: pandas>=0.24.0
Requires-Dist: h5py>=3.0.0
Requires-Dist: mdanalysis>=2.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: platform
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MiMiCPy
MiMiCPy is the companion library to the MiMiC framework for streamline preparation of input files. It includes a suite of command line tools and plugins for PyMOL/VMD. Visit the [MiMiC homepage](https://mimic-project.org/) for more details and documentation.

## Requirements

### Python
- Python >= 3.5, < 3.12 (Python 3.11 and below)

### Core Dependencies
- pandas >= 0.24.0
- numpy >= 1.12.0

### Force Matching Module
The force matching module requires additional dependencies:
- h5py >= 3.0.0
- MDAnalysis >= 2.0
- GROMACS (must be installed and accessible in the system PATH)

### Optional
- PyMOL (for PrepQM plugin) - tested with version 2.3.4
- VMD (for PrepQM plugin) - tested with version 1.9.4a38

## Installation
To install, run the following command:

```
pip install mimicpy
```

The PrepQM plugins for PyMOL and/or VMD can be optionally installed by running:

```
mimicpy_plugin_installer -pymoldir /path/to/plugin/ -vmddir /path/to/plugin/
```

The path to the plugin is usually either the path to the PyMOL/VMD installation, or the user home directory.

## Demo
A demo of atom selection for the QM region, and generation of the MiMiC-based CPMD input file using MiMiCPy is shown below.
```console
user@system:~$ mimicpy prepqm -top acetone.top -coords acetone.gro


 	                ***** MiMiCPy *****

 	 For more information type mimicpy [subcommand] --help

=====> Running prepqm <=====


**Reading topology**

Cannot find path to Gromacs installation.
Read atoms from acetone.itp.
No atoms found in acetone.top.

Some atom types had no atom numbers information.
They were guessed as follows:

+---------------------+
| Atom Type | Element |
+---------------------+
|     c     |    C    |
+---------------------+
|     c3    |    C    |
+---------------------+
|     o     |    O    |
+---------------------+
|     hc    |    H    |
+---------------------+

**Reading coordinates**  |Done

Please enter selection below. For more information type 'help'
> add resname is ACT
> q
Using default values for maxstep and timestep
Wrote Gromacs index file to index.ndx
Wrote new CPMD input script to cpmd.inp

=====> Done <=====

```

## Force Matching

The force matching module in MiMiCPy automates the parameterization of molecular mechanics (MM) force field parameters by fitting to reference QM/MM data. It optimizes both non-bonded interactions (atomic charges via DRESP) and bonded interactions (bonds, angles, dihedrals) to reproduce QM forces and electrostatic properties.

### Required Input Files

The force matching workflow requires the following input files:

- `-top`: GROMACS topology file (`.top`)
- `-sele`: QM region selection file (`.txt` or `.dat`) - specifies which atoms are in the QM region
- `-fmdata`: Force matching data file (`.json` or `.h5`) - contains QM/MM reference data (forces, charges, electrostatic potentials/fields)
- `-fi`: Force matching input file (`.dat`) - configuration file with optimization parameters
- `-trr`: GROMACS trajectory file (`.trr`) - trajectory from QM/MM simulation
- `-ndx`: GROMACS index file (`.ndx`) - atom index groups
- `-coords`: Coordinate file (`.gro`) - initial structure
- `-mdp`: GROMACS MDP file (`.mdp`, optional) - MD parameters for force recalculation

### Basic Usage

The basic force matching command is:

```console
mimicpy fm -top system.top -sele qm_selection.txt -fmdata fm_data.json -fi fm_input.inp -trr trajectory.trr -ndx index.ndx -coords system.gro -mdp run.mdp
```

### Common Options

- `-dresp`: Run only DRESP charge optimization (skip bonded parameter optimization)
- `-opt_ff`: Run only force field parameter optimization (skip DRESP, uses existing charges)
- `-grid_search`: Perform grid search over DRESP weight parameters (wv, we, wh)
- `-ff`: Path to force field data directory (optional)
- `-gmx`: GROMACS executable name (default: `gmx`)
- `-n_processes`: Number of processes for parallel force computation

