Chemiscope: interactive structure-property explorer for materials and molecules

Chemiscope is a graphical tool for the interactive exploration of materials and molecular databases, correlating local and global structural descriptors with the physical properties of the different systems; as well as a library of re-usable components useful to create new interfaces.

Citing chemiscope

Chemiscope is distributed under an open-source license, and you are welcome to use it and incorporate it into your own research and software projects. If you find it useful, we would appreciate a citation to the chemiscope paper:

S. Chorna, J. Lála, Q. Xu, R. K. Cersonsky, G. Fraux, M. Ceriotti, Chemiscope 1.0: interactive exploration of atomistic data from analysis to dissemination. Journal of Open Source Software 11 (122), 10380 (2026)

The original chemiscope paper may also be cited:

G. Fraux, R. K. Cersonsky, M. Ceriotti, Chemiscope: Interactive Structure-Property Explorer for Materials and Molecules. Journal of Open Source Software 5 (51), 2117 (2020)

If you incorporate chemiscope components into a software project, a link back to the chemiscope homepage (https://chemiscope.org) is the preferred form of acknowledgement.

Documentation

You may be interested in particular about how to create a visualization of your own dataset.

If you would like to generate a simple chemiscope for your dataset, check one of the many examples.

Getting help for using chemiscope

If you want to get help when using chemiscope either as a JavaScript/TypeScript library inside your own project, for creating input files for the default visualizer at https://chemiscope.org, or if you want to propose new features you can open a Github issue with your question; or send an email to the developers (you can find these emails on the lab webpage: https://www.epfl.ch/labs/cosmo/people/)

Getting the python package and using chemiscope as a notebook widget

Using chemiscope as an interactive widget — in Jupyter, JupyterLab, marimo, or Google Colab — should be as easy as

pip install chemiscope

This also allows to generate chemiscope JSON files that can be viewed on http://chemiscope.org

If you need to build and install a development version, you should have all the npm stack installed, and then just run

git clone https://github.com/lab-cosmo/chemiscope
cd chemiscope
pip install .

Getting and running the web app locally

git clone https://github.com/lab-cosmo/chemiscope
cd chemiscope
npm install
npm start

# navigate to localhost:8080

Building the code to use it in other projects

git clone https://github.com/lab-cosmo/chemiscope
cd chemiscope
npm install
npm run build

# Include dist/chemiscope.min.js in your own web page

See [app/] or the documentation for an example of how to create a webpage using chemiscope.

chemiscope.explore option

Chemiscope provides a way to automatically explore datasets, using machine learning representations and dimensionality reduction. For examples and detailed usage, refer to the related documentation.

To use the explore functionality as well as chemiscope.metatomic_featurizer, you'll need to install the required dependencies with:

pip install chemiscope[explore]

streamlit component

If you need more tight integration of the viewer and data processing in a web app settings, you can try a streamlit component based on chemiscope. Install the dependencies with

pip install chemiscope[streamlit]

and try a demo by cloning the repository and running the example

streamlit run python/streamlit/example/app.py

which should automatically launch a browser open at the page served on localhost.

sphinx and sphinx-gallery integration

Chemiscope provides also extensions for sphinx and sphinx-gallery to include chemiscope viewers within the documentation of a Python package. See the documentation for a discussion of the setup and a few examples.

License and contributions

If you are interested in contributing to chemiscope, please have a look at our contribution guidelines

Chemiscope itself is distributed under the 3-Clauses BSD license. By contributing to this repository, you agree to distribute your contributions under the same license.

This project is maintained by @ceriottm and @sofiia-chorna, who will reply to issues and pull requests opened on this repository as soon as possible. You can mention them directly if you did not receive an answer after a couple of days.

It was previously maintained by @Luthaf (2019 to 2026), many thanks to them for their work making chemiscope awesome!