cpmd-cube-tools 0.993
A python library and tool to read in and manipulate Gaussian and CPMD cube files.
Requires Python: >=3.6

# cube_tools

A easy-to-use python program to read in and manipulate Gaussian and CPMD cube files.
This code allows you to:
    Read and write Gaussian/CPMD cube files,
    Perform VDD charge analysis (Voronoi charges, Voronoi electron charges, Voronoi deformation density (Voronoi charges of delta_rho ), etc.),
    and more ...

If you have any questions on the usage/expansion of this code, please write to me via email "lyuwade@gmail.com" titled with "cpmd_cube_tools: your question".

If you want to publish your results obtained (partially) from this software,
please cite this paper:"On the accuracy of molecular simulation-based predictions
of koff values: a Metadynamics study, DOI: https://doi.org/10.1101/2020.03.30.015396".

# Installation:

pip install cpmd_cube_tools  

# Input files and format:

## 1. At least one Cube file, it can be generated by CPMD, CP2K, Gaussian, or other softwares. If you are going to analyze the Voronoi deformation density, please supply a cube file with delta_rho

## 2. (Optional) GEOMETRY file, it is required if your cube file is generated by CPMD/MIMIC QM/MM calculation.

## 3. (Optional) CPMD/MIMIC input file, it specifies the projection of the atoms order of pdb/gro to the CPMD internal atoms order (the format please see an example file in our test dataset). If your cube file was not generated via CPMD/MIMIC, just ignore this, and then use option "-mol qm" or specify explicitly the indexs of the atoms you wanted to consider via option "-mol qm,id0,id1,id2,..."    

# Outputs:

## 1. vdd_charges_all.csv: the vdd charges of all atoms listed in cube file

## 2. vdd_charges_mol.csv: the vdd charges of the selected atoms

## 3. dvdd_chargs_all.csv: the vdd charges, those contributed from electrons only or from delta_rho, of all atoms listed in cube file

## 4. dvdd_chargs_mol.csv: the vdd charges, those contributed from electrons only or from delta rho, of the selected atoms

## 5. *_corrected.cube: the corrected cube file when GEOMETRY file is supplied


# Example 1: run as an executable tool
#show the help

cubetools.py -h

# vdd analysis with cube file only

cubetool.py test/DENSITY.cube -vdd yes

# vdd analysis with cube file only, for electrons only or for {\Delta \rho}

cubetool.py test/DENSITY.cube -dvdd yes


#correct cube file

cubetool.py test/DENSITY.cube -g test/GEOMETRY

#perform vdd calculation with cube data and GEOMETRY files only

cubetool.py test/DENSITY.cube -g test/GEOMETRY -vdd yes -mol qm

#perform vdd calculation with cube data, GEOMETRY, and mimic input files

cubetool.py test/DENSITY.cube -g test/GEOMETRY -inp test/mm2qm_overlap.inp -vdd yes -mol mol

#perform vdd calculation for electrons only

cubetool.py test/DENSITY.cube -g test/GEOMETRY -inp test/mm2qm_overlap.inp -dvdd yes -mol mol


# Example 2: run as a library

from cpmd_cube_tools.api import *

#load the test data

cptest()

#Load a cube file

cube0=cube('test/DENSITY.cube')

## Correct cube file

cube0.correct_cube('test/GEOMETRY')

## Calculate the vdd charges

vddcharge, vddcube=cube0.cube2vdd_test('test/GEOMETRY', 'test/mm2qm_overlap.inp')

## show the vdd charges

print(vddcharge)

## Calculate the vdd charge with customized atoms selection

#e.g. select the first 5 atoms in the cube file

vddcharge, vddcube=cube0.cube2vdd('test/GEOMETRY', 'test/mm2qm_overlap.inp','qm,0,1,2,3,4')

#e.g. select the first 5 atoms in the mm atom order list

vddcharge, vddcube=cube0.cube2vdd('test/GEOMETRY', 'test/mm2qm_overlap.inp','mm,0,1,2,3,4')


## Calculate the vdd charges of electrons only

vddcharge, vddcube=cube0.cube2dvdd_test('test/GEOMETRY', 'test/mm2qm_overlap.inp')


## Calculate the vdd charges of electrons only, with customized atoms selection

#e.g. select the first 5 atoms in the test cube file

vddcharge, vddcube=cube0.cube2dvdd('test/GEOMETRY', 'test/mm2qm_overlap.inp','qm,0,1,2,3,4')

#e.g. select the first 5 atoms in the mm atom order list

vddcharge, vddcube=cube0.cube2dvdd('test/GEOMETRY', 'test/mm2qm_overlap.inp','mm,0,1,2,3,4')

# Example 3: a test python script

test.py




# Acknowledgements


If you want to publish your results obtained (partially) from this software, please cite this paper:'Accuracy of molecular simulation-based predictions of koff values: a Metadynamics study', DOI: https://doi.org/10.1021/acs.jpclett.0c00999

This code is partially developed based on the Cube-Toolz @ https://github.com/funkymunkycool/Cube-Toolz/blob/master/cube_tools.py



# LICENSE


Copyright (c) 2020 The Python Packaging Authority
Author: Wenping Lyu
Email:  lyuwade@gmail.com

Academical use only!
Permission is hereby granted, free of charge, to any person obtaining a copy of 
this software and associated documentation files (the "Software") for academical
useage, including the rights to use, copy, modify, and merge.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.