https://github.com/lab-cosmo/chemiscope
An interactive structure/property explorer for materials and molecules
https://github.com/lab-cosmo/chemiscope
hacktoberfest materials-science molecule visualization web
Last synced: 6 months ago
JSON representation
An interactive structure/property explorer for materials and molecules
- Host: GitHub
- URL: https://github.com/lab-cosmo/chemiscope
- Owner: lab-cosmo
- License: bsd-3-clause
- Created: 2019-10-03T09:59:42.000Z (about 6 years ago)
- Default Branch: main
- Last Pushed: 2025-05-12T22:49:12.000Z (6 months ago)
- Last Synced: 2025-05-12T23:32:34.954Z (6 months ago)
- Topics: hacktoberfest, materials-science, molecule, visualization, web
- Language: TypeScript
- Homepage: http://chemiscope.org
- Size: 39.3 MB
- Stars: 145
- Watchers: 19
- Forks: 39
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- Contributing: Contributing.md
- License: LICENSE
Awesome Lists containing this project
- best-of-atomistic-machine-learning - GitHub - 26% open · ⏱️ 23.10.2025): (Visualization)
README
# Chemiscope: interactive structure-property explorer for materials and molecules
[](https://github.com/lab-cosmo/chemiscope/actions/workflows/tests.yml)
[](https://doi.org/10.21105/joss.02117)
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](https://doi.org/10.21105/joss.02117):
> 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](https://chemiscope.org/docs/)
You may be interested in particular about how to [create a visualization of your
own dataset](https://chemiscope.org/docs/manual/input.html).
If you would like to generate a simple chemiscope for your dataset, check one
of the many [examples](https://chemiscope.org/docs/examples/index.html).
## Getting help for using chemiscope
If you want to get help when using chemiscope either as a JavaScript/TypeScript
library inside your own project; or for creating input files for the default
visualizer at https://chemiscope.org, you can open a [Github
issue](https://github.com/lab-cosmo/chemiscope/issues/new) 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 in Jupyter notebooks
Using chemiscope in a Jupyter notebook should be as easy as
```bash
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
```bash
git clone https://github.com/lab-cosmo/chemiscope
cd chemiscope
pip install .
```
## Getting and running the web app locally
```bash
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
```bash
git clone https://github.com/lab-cosmo/chemiscope
cd chemiscope
npm install
npm run build
# Include dist/chemiscope.min.js or dist/molecule-viewer.min.js
# in your own web page
```
See [app/] or the [documentation](https://chemiscope.org/docs/embedding.html)
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](https://chemiscope.org/docs/examples/explore.html).
To use the explore functionality, you'll need to install the required
dependencies with:
```bash
pip install chemiscope[explore]
```
To use `chemiscope.metatensor_featurizer` for providing your trained model
to get the features for `chemiscope.explore`, install the dependencies with:
```bash
pip install chemiscope[metatensor]
```
## 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](https://chemiscope.org/docs/python/sphinx.html)
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](Contributing.md)
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.