Skip to content

Commit

Permalink
Update reference and parameter table
Browse files Browse the repository at this point in the history
  • Loading branch information
nnn911 committed Nov 19, 2024
1 parent 7171415 commit 792fa84
Showing 1 changed file with 13 additions and 9 deletions.
22 changes: 13 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,27 +1,31 @@
# Score-based Denoising

This is a wrapper for *OVITO* around the "Score-based denoising for atomic structure identification" presented in this [graphite repo](https://github.com/LLNL/graphite/). Further information and the official citation on [arXiv](https://doi.org/10.48550/arXiv.2212.02421).
This is a wrapper for *OVITO* around the "Score-based denoising for atomic structure identification" presented in this [graphite repo](https://github.com/LLNL/graphite/). Further information can be found in their [publication](https://doi.org/10.1038/s41524-024-01337-z).

## Description

Score-based denoising iteratively subtracts thermal vibrations or other pertubations from atomistic trajectories.

As described by the original authors in their abstract:

*"We propose an effective method for removing thermal vibrations that complicate the task of analyzing complex dynamics in atomistic simulation of condensed matter. Our method iteratively subtracts thermal noises or perturbations in atomic positions using a denoising score function trained on synthetically noised but otherwise perfect crystal lattices. The resulting denoised structures clearly reveal underlying crystal order while retaining disorder associated with crystal defects. Purely geometric, agnostic to interatomic potentials, and trained without inputs from explicit simulations, our denoiser can be applied to simulation data generated from vastly different interatomic interactions. The denoiser is shown to improve existing classification methods such as common neighbor analysis and polyhedral template matching, reaching perfect classification accuracy on a recent benchmark dataset of thermally perturbed structures up to the melting point. Demonstrated here in a wide variety of atomistic simulation contexts, the denoiser is general, robust, and readily extendable to delineate order from disorder in structurally and chemically complex materials."*
*"We propose an effective method for removing thermal vibrations that complicate the task of analyzing complex dynamics in atomistic simulation of condensed matter. Our method iteratively subtracts thermal noises or perturbations in atomic positions using a denoising score function trained on synthetically noised but otherwise perfect crystal lattices. The resulting denoised structures clearly reveal underlying crystal order while retaining disorder associated with crystal defects. Purely geometric, agnostic to interatomic potentials, and trained without inputs from explicit simulations, our denoiser can be applied to simulation data generated from vastly different interatomic interactions. The denoiser is shown to improve existing classification methods, such as common neighbor analysis and polyhedral template matching, reaching perfect classification accuracy on a recent benchmark dataset of thermally perturbed structures up to the melting point. Demonstrated here in a wide variety of atomistic simulation contexts, the denoiser is general, robust, and readily extendable to delineate order from disorder in structurally and chemically complex materials."*

Hsu, T., Sadigh, B., Bertin, N., Park, C. W., Chapman, J., Bulatov, V., & Zhou, F. (2022). Score-based denoising for atomic structure identification (Version 3). arXiv. https://doi.org/10.48550/ARXIV.2212.02421
[Hsu, T., Sadigh, B., Bertin, N., Park, C. W., Chapman, J., Bulatov, V. & Zhou, F. Score-based denoising for atomic structure identification. npj Comput Mater 10, (2024).](https://doi.org/10.1038/s41524-024-01337-z)

## Parameters

The modifier can be found under the label "Denoise particle positions" in the OVITO Pro interface. The Python modifier class and the module are both called `ScoreBasedDenoising`.

- "Number of denoising steps" | `steps`: Number of denoising interations taken. More iterations require more time. You can check the mean displacement per iteration graph to assess convergence.
- "Nearest neighbor distance" | `scale` : Estimation of the nearest neighbor distance used to scale the coordinates before they are input into the model. If this is `None` OVITO will try to estimate the correct nearest neighbor distance.
- "Crystal structure / material system" | `structure` : Allows you to select one of: "FCC", "BCC", "HCP", or "SiO2", depending on your input structure. Note, that an SiO2 structure requires a type named "Si" and "O". If you don't want to use any of the default material systems you can select "Custom". In that case OVITO will not estimate the "Nearest neighbor distance" and it has to be provided by the user.
- "Model file path" | `model_path`: Allows you define a custom pytorch model. The model will be loaded from the path entered. If this is set to `None` the default models for "SiO2" or "Cu" shipped with [graphite](https://github.com/LLNL/graphite/) will be loaded.
- "Device" | `device`: Allows you to select your computing device from: "cpu", "cuda", "mps". Only available devices will be shown. Please read the "Installation" section for additional information.
- "Only selected" | `only_selected`: Apply the modifier only to the selected particles. Following the convention set by other modifiers, even atoms that are not selected will be used as neighbors.
## Parameters

| GUI label | Python name | Description |
|----------------------------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Number of denoising steps** | `steps` | Number of denoising iterations taken. More iterations require more time. You can check the mean displacement per iteration graph to assess convergence. |
| **Nearest neighbor distance** | `scale` | Estimation of the nearest neighbor distance used to scale the coordinates before they are input into the model. If this is `None`, OVITO will try to estimate the correct nearest neighbor distance. |
| **Crystal structure / material system** | `structure` | Allows you to select one of: "FCC", "BCC", "HCP", or "SiO2", depending on your input structure. Note that an SiO2 structure requires a type named "Si" and "O". If you don't want to use any of the default material systems, you can select "Custom". In that case, OVITO will not estimate the "Nearest neighbor distance" and it has to be provided by the user. |
| **Model file path** | `model_path` | Allows you to define a custom PyTorch model. The model will be loaded from the path entered. If this is set to `None`, the default models for "SiO2" or "Cu" shipped with [graphite](https://github.com/LLNL/graphite/) will be loaded. |
| **Device** | `device` | Allows you to select your computing device from: "cpu", "cuda", "mps". Only available devices will be shown. Please read the "Installation" section for additional information. |
| **Only selected** | `only_selected` | Apply the modifier only to the selected particles. Following the convention set by other modifiers, even atoms that are not selected will be used as neighbors. |

## Example

Expand Down

0 comments on commit 792fa84

Please sign in to comment.