Wulff shape and morphology evolution component

[CifLord]

Component will allow users to:

• Input surface energies, crystal shape and miller indices or vasprun.xml file to visualize an interactive Wulff shape

• Can upload a vasprun.xml file or accept manual parameters

• plotly dash interface will allow:

• Specs of each surface when hovering mouse over a specific facet on the Wulff shape, i.e. Wulff area fraction, surface energy, miller index

• Morphology evolution, can take in non-stoichiometric or adsorbed/doped surfaces. User can select chemical potentials as constant or variable. Draggable chemical potential bar will allow for user to vary surface energy (and thus visual morphology evolution) as a function of chemical potential.

Question: For this component, do we want to add the plotly interface for WulffShapes to pymatgen or crystaltoolkit for now?

[mkhorton]

Hi @richardtran415, thanks for creating this issue! I meant to reply a few days ago, apologies.

This sounds excellent. In terms of features, this sounds good. My only hesitation is the vasprun.xml upload, how would this work exactly? I wouldn't think there'd be enough information in a single vasprun to do a Wulff analysis?

For this component, do we want to add the plotly interface for WulffShapes to pymatgen or crystaltoolkit for now?

We have two options:

(1) For now, to Crystal Toolkit. The first step to making this component will to make a Scene describing the Wulff shape using the classes here: https://github.com/materialsproject/crystaltoolkit/blob/master/crystal_toolkit/core/scene.py

Currently, these Scene classes live in Crystal Toolkit, so the Wulff code will have to live here too. A good place to put it will be inside crystal_toolkit/renderables/wulff.py, and then we can easily move it to pymatgen later as necessary.

Specs of each surface when hovering mouse over a specific facet on the Wulff shape

We would then need to add support to our three.js renderer for this (this lives here https://github.com/materialsproject/crystaltoolkit/blob/97c7943908b82e503cf475e47240b8fb5e2b8294/src/lib/components/Simple3DScene.js#L528). We need to add this feature for other use cases anyway, but just wanted to give a heads up that we can't currently do this yet.

or (2) As an alternative, we could have a implementation purely as a Plotly graph, this would be a lot simpler. We would have less control over rendering fidelity, but honestly for a Wulff shape (where we know it's just going to be a single 3D shape), this might be the better option -- and in this case, generating the graph could go directly into pymatgen.

[mkhorton]

I'm leaning towards option (2) actually, thinking about it.

[CifLord]

• For a plotly based Wulff shape app, I was thinking of a compromise between simple and flexible. The surface energy needs two types of calculations:

1. the chemical potential reference: bulk structures (for the substrate), molecular gas (for adsorbates), or elemental bulk for non-stoichiometric surfaces
2. the total energy of the slab (w or w/o substitutional dopants, adsorbates, nonstoichiometry, etc)

My logic was as long as the user can drag/drop their vasprun.xml for the slab calculations (along with corresponding hkl) and the reference calculations (or they also have the option of choosing the reference from MP instead), the app can convert it to a ComputedStructureEntry which the SurfaceEnergyPlotter takes in to generate WulffShapes as a function of chemical potential (if applicable). Another feature of the app would be a free shape builder wherein the user can provide any surface energy, hkl, crystal system and stoichiometry they want to visualize the morphology and its evolution.

• For the specs, at the moment I'm just using the hoverinfo in plotly to display the information I want in the Dataframe I fed it (hkl, area fraction, surface energy etc...). That seems to do the job, but I'll look into the Simple3DScene.js as well to see how to make this better.

• If we go with option (2), I'm thinking we can use this as a test case for converting all the pymatgen plotting objects to a plotly and matplotlib friendly DataFrame as @shyuep previously suggested. Right now the common parameters needed to build a matplotlib object and a plotly Mesh3d object are just the points needed to create the polyhedron. We can have some method in the WulffShape object like .get_wulff_df() which can be called by .get_matplotlib_plot() or .get_plotly_plot(). Though this brings up another question which is more related to pymatgen than crystaltoolkit, should we have a generalized converter for dataframes into matplotlib and plotly and therefore a standard DF for all plotting objects or should each plotting object, e.g. WulffShape, DoS, BandStructure, have their own method of converting their own DF into matplotlib and plotly?

My only concern is how slow would the morphology evolution aspect of this app would be since it would essentially be regenerating a WulffShape every time the user toggles around the chemical potential. But I'll figure that out along the way.

[mkhorton]

For the specs, at the moment I'm just using the hoverinfo in plotly to display the information I want in the Dataframe I fed it (hkl, area fraction, surface energy etc...). That seems to do the job, but I'll look into the Simple3DScene.js as well to see how to make this better.

This sounds fine to me. Simple3DScene exists primarily for crystal structures where the fidelity of the plotly plots is insufficient, but for Wulff shapes this is probably unnecessary.

If we go with option (2), I'm thinking we can use this as a test case for converting all the pymatgen plotting objects to a plotly and matplotlib friendly DataFrame

Yes, sounds good to me ... I don't think we should have a standard converter for data frames however, it gets really messy ... consider that for a 3D plot you need to define lines, surfaces, points, hover info, you essentially have to define a whole secondary schema, and not all of it fits neatly into a table format. I think what we should do instead is adopt the Plotly JSON schema as a de facto standard, use that in a .get_plot() method, but have an automatic plotly->matplotlib adaptor for a .get_matplotlib_plot() method. Just to be clear, I'm not against a .get_dataframe() method where it makes sense to be able to get raw data, just that it should be free-form and optional.

My proposal here would be to start with a minimal component (table of lattice planes + surface energies, 3D plot of the Wulff shape with hover info), make sure that works quickly and reliably, and then build up from there. If we add too much interactivity (uploading files etc.) at the beginning, it's very easy to end up in "callback hell" if we're not careful.

WIP PRs are very welcome if you want to get started.

Regarding the .get_plot(), we're working on developing Plotly code in e.g. bandstructure, xrd and phase diagrams. We've been holding them here until they're finished, then we can move them to their respective pymatgen classes.

[mkhorton]

The current status of this issue is that Wulff shapes are now being plotted in the new Materials Project website via Crystal Toolkit and using the plotly-based Wulff plotting added to pymatgen by @CifLord, however a formal component is still to be written.

This issue will remain open until this is done, because a formal component is necessary for (a) ease of maintainability in future, and (b) to allow external users to use Wulff shapes in their apps.