update README.md

Update README.md

README.md

@@ -1,7 +1,7 @@
 # MolVoxel: Molecular Voxelization Tool
 MolVoxel is an easy-to-use **Molecular Voxelization Tool** implemented in Python.
 
-It requires few dependencies, so you can install it very simply. If you want to use numba version, just install numba.
+It requires few dependencies, so it's very simple to install and use. If you want to use numba version, just install numba additionally.
 
 ### Dependencies
 
@@ -13,16 +13,27 @@ It requires few dependencies, so you can install it very simply. If you want to
   - PyTorch - `from molvoxel.voxelizer.torch import Voxelizer`, **CUDA Available**
   - RDKit, pymol-open-source
 
+### Citation
+
+```
+@article{seo2023pharmaconet,
+  title = {PharmacoNet: Accelerating Large-Scale Virtual Screening by Deep Pharmacophore Modeling},
+  author = {Seo, Seonghwan and Kim, Woo Youn},
+  journal = {arXiv preprint arXiv:2310.00681},
+  year = {2023},
+  url = {https://arxiv.org/abs/2310.00681},
+}
+```
+
 ## Quick Start
 
 ### Create Voxelizer Object
 ```python
 import molvoxel
-
-# Default (gaussian sigma = 0.5)
+# Default (Gaussian sigma = 0.5)
 voxelizer = molvoxel.create_voxelizer(resolution=0.5, dimension=64, density_type='gaussian', library='numpy')
-# Set gaussian sigma = 0.5, spatial dimension = (48, 48, 48)
-voxelizer = molvoxel.create_voxelizer(dimension=48, density_type='gaussian', sigma=0.5, library='numba')
+# Set gaussian sigma = 1.0, spatial dimension = (48, 48, 48)
+voxelizer = molvoxel.create_voxelizer(dimension=48, density_type='gaussian', sigma=1.0, library='numba')
 # Set binary density
 voxelizer = molvoxel.create_voxelizer(density_type='binary', library='torch')
 # CUDA
@@ -36,23 +47,21 @@ voxelizer = molvoxel.create_voxelizer(library='torch', device='cuda')
 from rdkit import Chem  # rdkit is not required packages
 import numpy as np
 
-def get_atom_features(atom) :
-  symbol, aromatic = atom.GetSymbol(), atom.GetIsAromatic()
-  return [symbol == 'C', symbol == 'N', symbol == 'O', symbol == 'S', aromatic]
+def get_atom_features(atom):
+    symbol, aromatic = atom.GetSymbol(), atom.GetIsAromatic()
+    return [symbol == 'C', symbol == 'N', symbol == 'O', symbol == 'S', aromatic]
 
-mol = Chem.SDMolSupplier('test/10gs/ligand.sdf')[0]
+mol = Chem.SDMolSupplier('./test/10gs/10gs_ligand.sdf')[0]
 channels = {'C': 0, 'N': 1, 'O': 2, 'S': 3}
-coords = mol.GetConformer().GetPositions()                  # (V, 3)
-center = coords.mean(axis = 0)                              # (3,)
-atom_types = [channels[atom.GetSymbol()] for atom in mol.GetAtoms()]
-atom_types = np.array(atom_types)                           # (V,)
-atom_features = [get_atom_features(atom) for atom in mol.GetAtoms()]
-atom_features = np.array(atom_features)                     # (V, 5)
-radii = 1.0
-
-image = voxelizer.forward_single(coords, center, radii)                   # (1, 64, 64, 64)
-image = voxelizer.forward_types(coords, center, atom_types, radii)        # (4, 64, 64, 64)
-image = voxelizer.forward_features(coords, center, atom_features, radii)  # (5, 64, 64, 64)
+coords = mol.GetConformer().GetPositions()                                      # (V, 3)
+center = coords.mean(axis=0)                                                    # (3,)
+atom_types = np.array([channels[atom.GetSymbol()] for atom in mol.GetAtoms()])  # (V,)
+atom_features = np.array([get_atom_features(atom) for atom in mol.GetAtoms()])  # (V, 5)
+atom_radius = 1.0                                                               # (scalar)
+
+image = voxelizer.forward_single(coords, center, atom_radius)                   # (1, 64, 64, 64)
+image = voxelizer.forward_types(coords, center, atom_types, atom_radius)        # (4, 64, 64, 64)
+image = voxelizer.forward_features(coords, center, atom_features, atom_radius)  # (5, 64, 64, 64)
 ```
 
 #### PyTorch - Cuda Available
@@ -67,9 +76,9 @@ center = torch.FloatTensor(center).to(device)               # (3,)
 atom_types = torch.LongTensor(atom_types).to(device)        # (V,)
 atom_features = torch.FloatTensor(atom_features).to(device) # (V, 5)
 
-image = voxelizer.forward_single(coords, center, radii)                   # (1, 64, 64, 64)
-image = voxelizer.forward_types(coords, center, atom_types, radii)        # (4, 32, 32, 32)
-image = voxelizer.forward_features(coords, center, atom_features, radii)  # (5, 32, 32, 32)
+image = voxelizer.forward_single(coords, center, atom_radius)                   # (1, 64, 64, 64)
+image = voxelizer.forward_types(coords, center, atom_types, atom_radius)        # (4, 32, 32, 32)
+image = voxelizer.forward_features(coords, center, atom_features, atom_radius)  # (5, 32, 32, 32)
 ```
 ---
 
@@ -90,7 +99,58 @@ pip install -e .
 # pip install -e '.[numpy, numba, torch, rdkit]'
 ```
 
+---
+
+## Voxelization
+
+### Input
+
+- $X \in \mathbb{R}^{N\times3}$ : Coordinates of $N$ atoms
+- $R \in \mathbb{R}^N$ : Radii of $N$ atoms
+- $F \in \mathbb{R}^{N\times C}$ : Atomic Features of $N$ atoms - $C$ channels.
+
+### Kernel
+
+$d$: distance, $r$: atom radius
+
+#### Gaussian Kernel
+
+$\sigma$: gaussian sigma (default=0.5)
+
+$$
+f(d, r, \sigma) =
+\begin{cases}
+	\exp
+		\left(
+			-0.5(\frac{d/r}{\sigma})^2
+		\right)	& \text{if}~d \leq r \\
+	0					& \text{else}
+\end{cases}
+$$
+
+#### Binary Kernel
+
+$$
+f(d, r) =
+\begin{cases}
+	1	& \text{if}~d \leq r \\
+	0	& \text{else}
+\end{cases}
+$$
+
+### Output
+
+- $I \in \mathbb{R}^{D \times H \times W \times C}$ : Output Image with $C$ channels.
+- $G \in \mathbb{R}^{D\times H\times W \times 3}$ : 3D Grid of $I$.
+
+$$
+I_{d,h,w,:} = \sum_{n}^{N} F_n \times f(||X_n - G_{d,h,w}||,R_n,\sigma)
+$$
+
+---
+
 ## RDKit Wrapper
+
 ``` python
 # RDKit is required
 from molvoxel.rdkit import AtomTypeGetter, BondTypeGetter, MolPointCloudMaker, MolWrapper