Skip to content

Integrate LOBSTER apps into crystal toolkit#459

Open
JaGeo wants to merge 32 commits into
materialsproject:mainfrom
JaGeo:add_lobster_integration
Open

Integrate LOBSTER apps into crystal toolkit#459
JaGeo wants to merge 32 commits into
materialsproject:mainfrom
JaGeo:add_lobster_integration

Conversation

@JaGeo

@JaGeo JaGeo commented Apr 26, 2025

Copy link
Copy Markdown
Member

This is the PR to integrate LOBSTER into the Crystal Toolkit.

See below for a detailed explanation of the PR by @naik-aakash !

@JaGeo JaGeo changed the title Add LobsterNeighbors to list of bonding strategies Integrate LOBSTER apps into crystal toolkit Apr 26, 2025
@naik-aakash

naik-aakash commented May 9, 2025

Copy link
Copy Markdown
Contributor

StructureMoleculeComponent update

  • @JaGeo added option to use LobsterNeighbors in structure visualization

CohpAndDosComponent Features

  • Get relevant bonds interactive cohp plots alongside dos from Lobstery by means of LobsterPy and existing dos plotter in crystaltoolkit
  • Include Bonding analysis summary and calculation quality texts
  • Include visualization of LobsterEnv identified environments
  • Hovering over atoms shows Mulliken charges and edges show the ICOHP values in the visualizer

Example rendered app

App_overview

Todos (Will be worked on once app layout is finalized))

  • Exception handling needs to be implemented
  • Add tests

Open questions and things to improve

  • App loading is currently slow as we pass in completecohp objects (this is quite large) as due to inherent nature of how ploty/dash handles callbacks, lot of time is spent in serialization and deserialization of this object

  • Vasprun.xml file seems to have issues with serialization via plotly so, I think, simple fix would be to just make a small change in pymatgen - Have included temporary workaround for it in the example script here.

  • Icohpcollection object also has serialization issues and currently a fix is a WIP via this Add custom as_dict/from_dict method for proper initialization of attributes of IcohpCollection pymatgen#4391

  • With the current changes LobsterNeighbors can also be used to visualize structure on the Main MP website. Is this desirable ? We think could be nice addition to already exisitng options.
    image

  • Need to agree on what would be best place to visualize LocalEnv identified from LobsterNeighbors, maybe in crystaltoolkit app ? (i.e move this part in localenv.py module ) or could be better to have all LOBSTER related information in one page as in current app layout?

  • What one can query over from MP website using mpid ? If we intend to provide complete taskdoc then we can then add option as in the app.

@esoteric-ephemera

esoteric-ephemera commented Sep 24, 2025

Copy link
Copy Markdown
Collaborator

@naik-aakash @JaGeo for this to be used on MP's site, we'll need any of the required outputs to be in the LobsterTaskDocument. The client will retrieve a LobsterTaskDocument and then use any fields, like CalcQualitySummary rather than rerunning Analysis.get_lobster_calc_quality_summary

(The client shouldn't depend on lobsterpy / need to call lobsterpy). Also to be clear, crystal toolkit shouldn't depend on emmet, but should use data that is available in the task document

The method you implemented is OK to keep as a from_files / from_directory method, but we'd also need something that operates on data after lobster is run

Can you double check that any data that is required for the app to work is included in the task document model? Any updates to the schema should be made against this branch in emmet (PR link)

@naik-aakash

Copy link
Copy Markdown
Contributor

Hi @esoteric-ephemera, thanks for the suggestion. I will look at the pinned emmet PR and raise a PR if I find anything is missing.

I will also try to make the changes in the client in the PR soon.

Comment thread crystal_toolkit/apps/examples/cohp.py Outdated
from crystal_toolkit.settings import SETTINGS


class CustomVasprun(Vasprun):

@esoteric-ephemera esoteric-ephemera Sep 25, 2025

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For this class, I would recommend against copying all of Vasprun.final_energy:

class CustomVasprun(Vasprun):

    @property
    def final_energy(self):
        return float(super().final_energy)

@naik-aakash

Copy link
Copy Markdown
Contributor

Hi @esoteric-ephemera , have one question. So, now the plan is that LobsterPy is already run as part of taskdoc generation, and we simply use the outputs from the taskdoc and render the app?

I did it this way because, in our initial discussions, it was emphasized that Postprocessing should not be part of Taskdoc, but rather that this app should handle it.

Curious about how the workflow pipeline would be now.

Once I start with this, I can better comment on the emmet PR.

@esoteric-ephemera

Copy link
Copy Markdown
Collaborator

Any "heavy" post-processing, or post-processing which requires raw output files like vasprun.xml, should happen in the build process for your data. In the current pipeline, the lobster build would be LobsterTaskDocument.from_directory

Ex: all derived MP data is built from TaskDoc objects, and not the raw VASP output - any necessary fields for apps/subsequent builds has to be in TaskDoc. The tasks collection is built from the TaskDoc.from_directory method currently

Light post-processing can occur in the app (e.g., the oxygen evolution graph drawing in the client) , but this should be

Let me know if that makes sense!

@naik-aakash

Copy link
Copy Markdown
Contributor

Hi @esoteric-ephemera , I made the changes are requested to directly work with taskdoc inputs. Made some tweaks and added some more options to enable more interactive anaylsis.

Here is screenshot of updated layout

image

Also I have an additional code that can create such visualization using plotly and dash. Have attached a short video of it here

Screencast.from.06.02.2026.17.03.33.webm

I could not figure out to reuse the Structuremolecule component for this, as I wanted clickable edges. Not sure if we like to have such thing on materials project website. Also as it relies on cohpcar objects, not sure if this can easily work on website. So have not pushed the code here yet.

Let me know what you think? Also if this additional app is desired, It would be great if anyone can help with modifying Structuremolecule component. If it is too much I can simply include it in LobsterPy and we can provide a button to tell users to make use of LobsterPy for more powerful interactive analysis.

@esoteric-ephemera

Copy link
Copy Markdown
Collaborator

Thanks, @naik-aakash! Looking good and perhaps @minhsueh has suggestions on how to modify / work with existing components

We can discuss this more, but would this ideally be included as a separate property tab for a material, or in a standalone app?

@naik-aakash

Copy link
Copy Markdown
Contributor

Thanks, @naik-aakash! Looking good and perhaps @minhsueh has suggestions on how to modify / work with existing components

We can discuss this more, but would this ideally be included as a separate property tab for a material, or in a standalone app?

Hi @esoteric-ephemera, we think it fits better as a separate tab in properties, as you suggested. Maybe a tab under Electronic structure would be an appropriate place?

@minhsueh

minhsueh commented Feb 9, 2026

Copy link
Copy Markdown
Collaborator

This looks great! I think the Electronic Structure tab is the perfect place for this. We can discuss further what needs to be integrated in next week's meeting. Note that the Structuremolecule will require additional React work if we decide to move forward with that option.

@naik-aakash

Copy link
Copy Markdown
Contributor

Hi @esoteric-ephemera , @minhsueh, I added the LobsterEnv analysis algorithm to localenv.py now and I simply reuse it in CohpAndDosComponent

Have also added a LobsterEnvUploadComponent in upload.py module that is part of the layout of the LocalEnv app, but only shows during the LobsterEnv algorithm is selected. It seems to work fine as of now. Maybe I might have overlooked something. Below is snapshot of the app run locally

Screenshot 2026-02-18 at 13-15-13 Crystal Toolkit

Also, not 100%: I didn't break anything in localenv.py. Had made some changes to how other algorithms accessed the data. It would be great if it were tested on your end as well.

Tagging @JaGeo here just to keep in the loop

import dash_mp_components as mpc
from dash.dependencies import Component, Input, Output
from dash.exceptions import PreventUpdate
from lobsterpy.plotting import InteractiveCohpPlotter

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please modify this direct import since lobsterpy is an optional dependency.

You can use FermiSurfaceComponent as a reference(here and here) for how this is handled.

trace.line.dash = "dot"
if trace.line.dash != "dot":
trace.name = f"{cohp_fig.data[ix].name} (spin ↑)"
legend_spin_down_name = trace.name.split(" (")

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add more information to the trace? Specifically, you can see that both Na (spin ↑) and Na1: 6 × Cl-Na (spin ↑) are solid red lines. Users who are familiar with Plotly know that detailed information appears when hovering over a trace. However, users who are new to Plotly may find this behavior confusing, especially when multiple traces overlap, making it difficult to determine which trace is being hovered over.

The simplest solution might be to append (COHP) or (DOS) to the legend labels so users can more easily distinguish the traces.

Image

struct,
obj_icohp,
obj_charge,
perc_strength_icohp,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you check and update the logic? I'm seeing that when the cutoff is set below 0.05, the following error message is displayed:

raise LookupError(f"No coordination geometry found with mp_symbol {mp_symbol!r}")
LookupError: No coordination geometry found with mp_symbol '18'

"noise_cutoff": 1e-3,
}

lobsterenv_analysis_options = [

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason we only allow all and cation-anion? Is it primarily due to computational cost or performance considerations? Totally fine with two options! I am just curious.

There are more options (source):

                    0 - NO_ADDITIONAL_CONDITION
                    1 - ONLY_ANION_CATION_BONDS
                    2 - NO_ELEMENT_TO_SAME_ELEMENT_BONDS
                    3 - ONLY_ANION_CATION_BONDS_AND_NO_ELEMENT_TO_SAME_ELEMENT_BONDS
                    4 - ONLY_ELEMENT_TO_OXYGEN_BONDS
                    5 - DO_NOT_CONSIDER_ANION_CATION_BONDS
                    6 - ONLY_CATION_CATION_BONDS

initial_data={"color_scheme": "Jmol", "color_scale": None},
)
# Create LobsterEnv upload component
self.lobsterenv_upload = LobsterEnvUploadComponent(

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add a toggle to disable self.lobsterenv_upload?

One use case on the site has LobsterTaskDoc directly as input, so the upload component would only be needed for local usage.

"The threshold can be set as a percentage of the strongest ICOHP/ICOBI/ICOOP in the structure, and can be adjusted using the slider below. "
)

lobsterenv_state = {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to define all the subcomponents here, given that they are repeated? Could we call CohpAndDosComponent.layout() directly instead?

return None


def _get_lobsterenv_inputs(data: dict):

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn’t these two functions, _get_lobsterenv_inputs and _extract_structure_from_data, be moved to cohp.py? They are only used for LOBSTER local-environment analysis, whereas localenv.py should serve as the general factory for all local-environment analyses.

)

struct = self.from_data(struct)
struct = _extract_structure_from_data(struct)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we need to replace the original code with _extract_structure_from_data here? These callbacks are for soap_analysis, soap_similarities, chemenv_analysis, and bondinggraph_analysis, so they shouldn’t use a structure-extraction function specific to the LOBSTER analysis.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants