Crystal Toolkit

Crystal Toolkit is not ready for the public yet! Please wait for a release announcement soon, thank you :-)

Installation and use

To use Crystal Toolkit, simply visit https://viewer.materialsproject.org (address subject to change).

If you would like to test Crystal Toolkit on your own computer, download and run our Docker image from DockerHub:

docker pull crystal_toolkit
docker container run -p 8000:8000 -e PMG_MAPI_KEY=YOUR_API_KEY_HERE crystal_toolkit

and then visit http://localhost:8000.

If you would like to use Crystal Toolkit for its library of UI components for your own Dash app, you can pip install it:

pip install crystal-toolkit

Easy viewing of crystal structures and molecules from Python

Installing Crystal Toolkit via pip also gives you the useful command view:

from crystal_toolkit import view_online
view_online(my_struct)  # returns https://viewer.materialsproject.org/?token=...

This will generate a link to view your crystal structure or molecule online.

In future, support for online, interactive viewing of other classes are planned, in addition to inline viewing in a Jupyter notebook.

Contributing

Contributions are welcome! We have an open and inclusive contribution policy.

Please use the Issues page to report bugs and feature requests, pull requests are also welcome. This is the first significant web app we've developed using Dash and we're still figuring out best practices, so comments on architectural choices are also welcome.

Technical guidelines on contributions are as follows:

Contribute an MPComponent

An MPComponent is designed to render an instance of an "MSONable" object from a Materials Project software code.

Currently there are MPComponents for the following classes:

pymatgen.core.Structure
pymatgen.core.Molecule
pymatgen.analysis.graphs.StructureGraph
pymatgen.analysis.graphs.MoleculeGraph

See the current Issues page for any components that still need implementing.

Before using any MPComponents in your app, you must register your app object and cache (if applicable) with Crystal Toolkit.

import crystal_toolkit as ct
ct.register_app() # Optional, but required for interactivity
ct.register_cache() # Optional, but often useful for performance

To use an MPComponent, the standard initializer takes an id like any other Dash component and contents which can be an instance of the corresponding MSONable class or None.

For example,

import crystal_toolkit as ct
struct_component = ct.StructureMoleculeComponent(my_struct, id="my_structure_visualizer")

Then, you can add its default layout to your app using struct_component.default_layout or, if you want more customizability, you can print(struct_component) and see what other layouts it supports (for example, it might have an optional set of controls associated with it).

Implementing an MPComponent

...

Contribute a Crystal Toolkit Panel

A PanelComponent is a sub-class

Implementing a PanelComponent

Contribute a React component

Some MPComponents require functionality not offered by core Dash components, for example the crystal viewer itself which requires 3D rendering capabilities.

If you need an additional React component, you will first need to set up your development environment using npm install ...

...simply create YourComponent.react.js in ~/src/components/, import it in ~/src/index.js, and run:

builder...

If you have any new dependencies, add them using npm install -S ....

Tests

Tests are ideal, however tests are not required to start contributing to Crystal Toolkit. Since Crystal Toolkit itself does not itself contain any new scientific analysis capabilities, but instead builds upon other libraries like pymatgen, comprehensive testing isn't as mission critical. However, tests are still encouraged wherever possible and the long-term health of this project will rely on good testing.

New React components should have an example added to usage.py and edit tests/?

New subclasses of MPComponent and PanelComponent can have tests written purely in Python, a good test for a PanelComponent would be to test the output of update_contents().

Acknowledgements

Thank you to all the authors and maintainers of the libraries Crystal Toolkit depends upon, and in particular pymatgen for crystallographic analysis and Dash from Plotly for their web app framework. Thank you to the NERSC Spin service for hosting the app and for technical support.

Contact

Please contact @mkhorton with any queries.

sivonxay/crystaltoolkit