Quickstart

This page shows a minimal path from RDKit molecules to a pandas DataFrame using the stock PaDEL JAR. Install with pip install "padelpy2[calc]". See Installation for Java and RDKit setup, Examples for a no-RDKit padeldescriptor notebook, and When to use which package for package choice.

Minimal example

Compute molecular weight-related descriptors for ethanol and benzene:

from rdkit import Chem
from rdkit.Chem import AllChem

from padelpy2 import Calculator
from padelpy2.descriptors import Weight

smiles = ["CCO", "c1ccccc1"]
mols = []
for smi in smiles:
    mol = Chem.AddHs(Chem.MolFromSmiles(smi))
    AllChem.Compute2DCoords(mol)
    mols.append(mol)

calc = Calculator([Weight])
df = calc(mols)
print(df)

By default the engine Name column is dropped from the DataFrame.

Default catalogs

Preset lists cover the stock descriptor catalogs and fingerprints:

from padelpy2 import Calculator, descriptors_2d, descriptors_3d, fingerprints

# Default shapes (column counts) for the stock catalogs:
# descriptors_2d → 1444 columns
# descriptors_3d → 431 columns  (molecules need 3D conformers)
# descriptors    → 1875 columns
# each fingerprint type → its n_bits columns

df_2d = Calculator(descriptors_2d)(mols)

3D descriptors require conformers (for example AllChem.EmbedMolecule). Without them, padelpy2 fails fast with a clear error before invoking Java.

Custom subsets and fingerprints

Mix descriptor classes and fingerprint types freely:

from padelpy2.descriptors import ALOGP, Crippen, Weight
from padelpy2.fingerprints import MACCSFingerprinter

calc = Calculator([ALOGP, Crippen, Weight, MACCSFingerprinter])
df = calc(mols)

Configuration

Pass a PaDELConfig to forward PaDEL CLI flags (threads, aromaticity detection, salt removal, and others). Example:

from padelpy2 import Calculator, PaDELConfig
from padelpy2.descriptors import Weight

cfg = PaDELConfig(threads=1, detectaromaticity=True)
df = Calculator([Weight], config=cfg)(mols)

For large molecule lists, optional chunk_size processes batches and concatenates results (default None keeps a single batch):

df = Calculator([Weight])(mols, chunk_size=50)

Keep the engine Name column with retain_names=True. Use on_error="nan" to isolate invalid molecules or failed chunks as NaN rows (default on_error="raise" remains fail-fast).

These options are UX parity for batching and error handling, not a claim of unique parallel performance.

Low-level padeldescriptor (padelpy-compatible keywords) is documented in the API Documentation and Architecture pages.