Welcome to the ChemML’s documentation!

ChemML is a machine learning and informatics program suite for the analysis, mining, and modeling of chemical and materials data.

ChemML is developed in the Python 3 programming language and makes use of a host of data analysis and ML libraries, as well as domain-specific libraries. The development follows a strictly modular and object-oriented design to make the overall code as flexible and versatile as possible.

Latest Version:

• to find out about the latest version and release history, click here

• source repository on github

• for a detailed list of changes, see the Changelog

Installation and Dependencies:

We strongly recommend you install ChemML in an Anaconda environment. The instructions to create the environment and install ChemML are as follows:

conda create --name chemml_env python=3.13
source activate chemml_env
# Make sure to run this command in a clean location
git clone https://github.com/hachmannlab/chemml.git
pip install ./chemml

Note: Here is a list of external libraries that will be installed with chemml:

• numpy

• pandas

• tensorflow

• rdkit

• scikit-learn

• matplotlib

• seaborn

• lxml

• openpyxl

• ipywidgets

• shap

• lime

• openbabel

  • (NOTE: Python 3.8 requires a separate conda install of openbabel)

  conda install -c conda-forge openbabel
  

• torch

• torchvision

Optional dependencies (user-installed):

• python-graphviz, nb_conda_kernels (for ChemML Jupyter wrapper)

• xgboost, lightgbm (if you want to include these models for AutoML screening)

• Additional PyTorch libraries depending on operating system and GPU configuration, see here.

Errors during installation:

After installing ChemML in an Anaconda environment, you may run into the following error with respect to the rdkit module:

ImportError: /lib64/libstdc++.so.6: version `CXXABI_1.3.9' not found

Solution: Activate the environment in which you have installed ChemML and use the following code:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/chemml_env/lib

Citation:

Please cite the use of ChemML as:

Main citation:

@article{chemml2019,
author = {Haghighatlari, Mojtaba and Vishwakarma, Gaurav and Altarawy, Doaa and Subramanian, Ramachandran and Kota, Bhargava Urala and Sonpal, Aditya and Setlur, Srirangaraj and Hachmann, Johannes},
journal = {ChemRxiv},
pages = {8323271},
title = {ChemML: A Machine Learning and Informatics Program Package for the Analysis, Mining, and Modeling of Chemical and Materials Data},
doi = {10.26434/chemrxiv.8323271.v1},
year = {2019}
}


Other references:

@article{chemml_review2019,
author = {Haghighatlari, Mojtaba and Hachmann, Johannes},
doi = {https://doi.org/10.1016/j.coche.2019.02.009},
issn = {2211-3398},
journal = {Current Opinion in Chemical Engineering},
month = {jan},
pages = {51--57},
title = {Advances of machine learning in molecular modeling and simulation},
volume = {23},
year = {2019}
}

@article{Hachmann2018,
author = {Hachmann, Johannes and Afzal, Mohammad Atif Faiz and Haghighatlari, Mojtaba and Pal, Yudhajit},
doi = {10.1080/08927022.2018.1471692},
issn = {10290435},
journal = {Molecular Simulation},
number = {11},
pages = {921--929},
title = {Building and deploying a cyberinfrastructure for the data-driven design of chemical systems and the exploration of chemical space},
volume = {44},
year = {2018}
}

@article{vishwakarma2019towards,
title={Towards autonomous machine learning in chemistry via evolutionary algorithms},
author={Vishwakarma, Gaurav and Haghighatlari, Mojtaba and Hachmann, Johannes},
journal={ChemRxiv preprint},
year={2019}
}

ChemML Library

• Introduction to ChemML Library
  • Citation:
• Input
  • Molecule
    • Construct a molecule using SMILES
    • Construct a molecule using 3D atomic coordinates
    • Construct a molecule using InChi
    • Visualize the molecule
    • Add or remove hydrogens
    • Convert chemical formats
    • Optimize XYZ geometry
• Represent
  • Feature Representation Methods in ChemML
    • Creating chemml.chem.Molecule object from molecule SMILES
    • Coulomb Matrix
    • Fingerprints from RDKit
    • Molecule tensors from chemml.chem.Molecule objects
    • Descriptors from RDKit
    • Descriptors from Mordred
    • Descriptors from PaDELPy
• Prepare
  • Prepare: Handling Missing Values
    • ChemML implements 4 strategies to handle missing values and interpolate, replace or remove them.
    • Strategy 1: Ignoring Rows
    • Strategy 2: Replacing With Zeros
    • Strategy 3: Interpolate
    • Strategy 3: Ignore Columns
  • Prepare: Remove Constant Columns and Outliers
    • Removing Constant Columns
    • Removing oultiers based on mean
    • Removing outliers based on median
  • Prepare: Feature Cleaning
    • Removing Highly Correlated Features
    • Removing Invariant and Low-Variance Features
    • Keeping Removed Columns in a Separate DataFrame
• Model
  • Build a Neural Network using ChemML
    • Fit the chemml.model.MLP model to the training data
    • Saving the ChemML model
    • Loading the saved ChemML model
    • Predict the densities for the test data
    • Evaluate model performance using chemml.utils.regression_metrics
    • Plot actual vs. predicted values
    • If the Underlying (TensorFlow/PyTorch) model is required …
    • Sometimes you may need the keras model without the output layer (for e.g., for transfer learning)
  • Neural Fingerprints
    • Splitting and preprocessing the data
    • Building the Neural Fingerprints
    • Building and training the neural network
    • Unified Neural Graph Fingerprint API with Engine Selection
    • Simplified Workflow: Direct SMILES-to-Model
• Optimize
  • Hyperparameter Optimization using chemml.optimization.GeneticAlgorithm
    • Defining hyperparameter space
    • Defining objective function
    • Optimize the model
    • Resume optimization
  • Hyperparameter optimization for multi-output models
    • Multioutput method 1: Scikit-learn MultiOutputRegressor wrapper
    • Multioutput method 2: Neural networks (ChemML MLP)
  • Feature Selection using chemml.optimization.GeneticAlgorithm
    • Defining hyperparameter space
    • Defining objective function
    • Optimize the feature space
    • New in v1.3.4: Tunable target feature lengths
  • Active Learning
    • Keras model example
    • Initialize active learning: EMC
    • Start the active search
    • Get a baseline: random sampling
    • Visualize distributions
    • Search in a loop
    • Create a video
• Visualize
  • Visualize
• AutoML
  • AutoML for Regression Model Screening
    • Load your data
    • Run autoML for a regression task
    • Validating AutoML-generated model
  • AutoML for Classification Model Screening
    • Load your data
    • Run autoML for a classification task
    • Validating AutoML-generated model
• Explain
  • Generating Deep Neural Network Model Explanations via ChemML’s Explain Module
    • The chemml.explain module has three eXplainable AI (XAI) methods - DeepSHAP, LRP, and LIME. It allows both local (for a single instance) and global (aggregated for multiple instances) explanations. The explainations are in the form of a relevance score attributed to each feature used to build the DNN model.
    • DeepSHAP Explanations
    • Visualizing local DeepSHAP explanations using a waterfall plot adapted from the shap library.
• Changelog
  • [1.3.5] - 2026-10-27
    • Added
    • Changed
    • Fixed/Miscellaneous
  • [1.3.4] - 2026-07-28
    • Added
    • Changed
    • Fixed/Miscellaneous
    • Notes
  • [1.3.3] - 2026-04-22
    • Added
    • Changed
    • Fixed/Miscellaneous
  • [1.3.2] - 2025-12-05
    • Added
    • Changed
    • Removed
    • Fixed
    • Technical Details

ChemML Wrapper

• Introduction to ChemML Wrapper
  • Step #1: prepare an input file
  • Step #2: run ChemML Wrapper
    • method one: Running in the Terminal
    • method two: Running in any Python Interpreter
  • Step #3: check the output directory
• ChemML Wrapper Tutorial
  • Input File Manual
    • Input File Overview
    • Specific Characters
    • General Rules
  • Input File GUI
  • Generate Morgan fingerprints from SMILES codes
  • Pyscript Usage
  • Build a simple ML model
  • Genetic Algorithm GUI tutorial
    • evaluate
    • error_metric
    • single_obj
    • space
    • test_hyperparameters

Published Models

• Published
  • Accelerated Discovery of High-Refractive-Index Molecules
    • Single Target DNNs
    • Physics Infused DNN
    • Transfer learning TZVP Polarizabilities
    • Citation

ChemML API

• ChemML API
  • Library API documentation
    • Chem module
    • Magpie_Python module
    • Initialization module
    • Datasets module
    • Preprocessing module
    • Models module
    • Optimization module
    • Visualization module
  • Wrapper API documentation
    • Table of Contents
    • Wrapper Reference

License:

ChemML is copyright (C) 2014-2026 Johannes Hachmann, Mojtaba Haghighatlari, Aditya Sonpal, Gaurav Vishwakarma, Aatish Pradhan and Nitin Murthy, all rights reserved. ChemML is distributed under 3-Clause BSD License (https://opensource.org/licenses/BSD-3-Clause).

About us:

Maintainers:

• Johannes Hachmann, hachmann@buffalo.edu

• Nitin Murthy, nitinmad@buffalo.edu

University at Buffalo - The State University of New York (UB)

Contributors:

• Doaa Altarawy (MolSSI): scientific advice and software mentor

• Gaurav Vishwakarma (UB): automated model optimization

• Ramachandran Subramanian (UB): Magpie descriptor library port

• Bhargava Urala Kota (UB): library database

• Aditya Sonpal (UB): graph convolution NNs and explainable AI (XAI)

• Srirangaraj Setlur (UB): scientific advice

• Venugopal Govindaraju (UB): scientific advice

• Krishna Rajan (UB): scientific advice

• Aatish Pradhan (UB): AutoML and Jupyter GUI developer

• Nitin Murthy (UB): Feature selection, AutoML developer

• We encourage any contributions and feedback. Feel free to fork and make pull-request to the “development” branch.

Acknowledgements:

• ChemML is based upon work supported by the U.S. National Science Foundation under grant #OAC-1751161 and in part by #OAC-1640867.

• ChemML was also supported by start-up funds provided by UB’s School of Engineering and Applied Science and UB’s Department of Chemical and Biological Engineering, the New York State Center of Excellence in Materials Informatics through seed grant #1140384-8-75163, and the U.S. Department of Energy under grant #DE-SC0017193.

• Mojtaba Haghighatlari received 2018 Phase-I and 2019 Phase-II Software Fellowships by the Molecular Sciences Software Institute (MolSSI) for his work on ChemML.