Feat: add issue templates and modified docs (#20)

* update docs

* add templates for github issues

* add mattersim logo

* update issue templates

* update readme

* update readme

* update readme

* fix typo

* update readme

* Update README.md

* Update index.rst

---------

Co-authored-by: Han Yang <hanyang@microsoft.com>

.github/ISSUE_TEMPLATE/01-bug-report.yml

@@ -0,0 +1,91 @@
+name: Bug Report
+description: Report a bug or unexpected behavior in MatterSim
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report a bug! Please provide detailed information.
+  
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we reach you if we need more information?
+      placeholder: email@example.com
+    validations:
+      required: false
+
+  - type: textarea
+    id: bug-description
+    attributes:
+      label: Bug Description
+      description: Provide a clear and concise description of the bug
+      placeholder: Describe what happened
+    validations:
+      required: true
+
+  - type: input
+    id: mattersim-version
+    attributes:
+      label: MatterSim Version
+      description: What version of MatterSim are you using?
+      placeholder: e.g., v1.0.0
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: What Python version are you using?
+      placeholder: e.g., 3.9.7
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction Steps
+      description: Detailed steps to reproduce the bug
+      placeholder: |
+        1. Install MatterSim with...
+        2. Run code with...
+        3. Observe the error
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected-behavior
+    attributes:
+      label: Expected Behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual-behavior
+    attributes:
+      label: Actual Behavior
+      description: What actually happened?
+    validations:
+      required: true
+
+  - type: textarea
+    id: error-logs
+    attributes:
+      label: Error Logs
+      description: Paste any error messages or full traceback
+      render: python
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our Code of Conduct
+      options:
+        - label: I agree to follow the project's Code of Conduct
+          required: true

.github/ISSUE_TEMPLATE/02-feature-request.yml

@@ -0,0 +1,62 @@
+name: Feature Request
+description: Suggest a new feature or improvement for MatterSim
+title: "[Feat]: "
+labels: ["feature-request"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        We're excited to hear your feature ideas! Please provide detailed information.
+
+  - type: input
+    id: contact
+    attributes:
+      label: Contact Details
+      description: How can we reach you if we need more information?
+      placeholder: email@example.com
+    validations:
+      required: false
+
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: Feature Description
+      description: Provide a clear and detailed description of the proposed feature
+      placeholder: Describe the feature you'd like to see
+    validations:
+      required: true
+
+  - type: textarea
+    id: motivation
+    attributes:
+      label: Motivation
+      description: Why would this feature be useful? What problem does it solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-solution
+    attributes:
+      label: Proposed Solution
+      description: Describe how you envision this feature being implemented
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: contribution
+    attributes:
+      label: Contribution Interest
+      description: Would you like to contribute to this feature?
+      options:
+        - label: I'm interested in potentially implementing this feature
+        - label: I can provide guidance, but cannot implement
+        - label: I'm just suggesting the feature for the community
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: By submitting this issue, you agree to follow our Code of Conduct
+      options:
+        - label: I agree to follow the project's Code of Conduct
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

MODEL_CARD.md

@@ -137,12 +137,16 @@ The checkpoints released in this repository are those trained on an internal imp
 ## Citation
 
 **BibTeX:**
-```bibtex
+```
 @article{yang2024mattersim,
-  title={Mattersim: A deep learning atomistic model across elements, temperatures and pressures},
-  author={Yang, Han and Hu, Chenxi and Zhou, Yichi and Liu, Xixian and Shi, Yu and Li, Jielan and Li, Guanzhi and Chen, Zekun and Chen, Shuizhou and Zeni, Claudio and others},
-  journal={arXiv preprint arXiv:2405.04967},
-  year={2024}
+      title={MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures}, 
+      author={Han Yang and Chenxi Hu and Yichi Zhou and Xixian Liu and Yu Shi and Jielan Li and Guanzhi Li and Zekun Chen and Shuizhou Chen and Claudio Zeni and Matthew Horton and Robert Pinsler and Andrew Fowler and Daniel Zügner and Tian Xie and Jake Smith and Lixin Sun and Qian Wang and Lingyu Kong and Chang Liu and Hongxia Hao and Ziheng Lu},
+      year={2024},
+      eprint={2405.04967},
+      archivePrefix={arXiv},
+      primaryClass={cond-mat.mtrl-sci},
+      url={https://arxiv.org/abs/2405.04967},
+      journal={arXiv preprint arXiv:2405.04967}
 }
 ```
 
@@ -156,7 +160,7 @@ The checkpoints released in this repository are those trained on an internal imp
 
 ### Out-of-Scope Use
 
-The model only supports atomistic simulations of materials and molecules. Any attemp and interpretation beyond that should be avoided.
+The model only supports atomistic simulations of materials and molecules. Any attempt and interpretation beyond that should be avoided.
 The model does not support generation of new materials as it is designed for materials simulation and property prediction only.
 The model is intended for research and experimental purposes. Further testing/development are needed before considering its application in real-world scenarios.
 

README.md

@@ -45,7 +45,7 @@ print(predictions)
 
 
 ## Reference
-If you use MatterSim, please cite our preprint on [arXiv](https://arxiv.org/abs/2405.04967):
+We kindly request that users of MatterSim version 1.0.0 cite our preprint available on arXiv:
 ```
 @article{yang2024mattersim,
       title={MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures}, 
@@ -59,6 +59,12 @@ If you use MatterSim, please cite our preprint on [arXiv](https://arxiv.org/abs/
 }
 ```
 
+> [!IMPORTANT]
+> We kindly ask users to **explicitly** specify the exact model version and checkpoint (e.g., **MatterSim-v1.0.0-1M**) when reporting results in academic papers or technical reports, rather than referring to the model generically as **MatterSim**. Precise versioning is crucial for ensuring reproducibility. For instance, the statement "_This benchmark was conducted using MatterSim-v1.0.0-1M_" serves as a good example.
+
+## Limitations
+MatterSim is designed specifically for atomistic simulations of bulk materials. Applications or interpretations beyond this scope should be approached with caution. For instance, when using the model for simulations involving surfaces, interfaces, or properties influenced by long-range interactions, the results may be qualitatively accurate but are not suitable for quantitative analysis. In such cases, we recommend fine-tuning the model to better align with the specific application.
+
 ## Trademarks
 
 This project may contain trademarks or logos for projects, products, or services.

docs/conf.py

@@ -43,7 +43,7 @@
 
 html_static_path = ["_static"]
 
-html_logo = "_static/mattersim.png"
+html_logo = "_static/mattersim-with-name.png"
 
 # -- Options for nbsphinx ----------------------------------------------------
 nbsphinx_allow_errors = True

docs/index.rst

@@ -23,24 +23,13 @@ Pre-trained Models
 
 We currently offer two pre-trained versions of MatterSim with **M3GNet** architecture:
 
-1. **mattersim-v1.0.0-1M**: A mini version of the model that is faster to run. 
-2. **mattersim-v1.0.0-5M**: A medium version of the model that is more accurate.
+1. **MatterSim-v1.0.0-1M**: A mini version of the model that is faster to run. 
+2. **MatterSim-v1.0.0-5M**: A larger version of the model that is more accurate.
 
 These models have been trained using the data generated through the workflows 
 introduced in the `MatterSim <https://arxiv.org/abs/2405.04967>`_ manuscript, which provides an in-depth 
 explanation of the methodologies underlying the MatterSim model.
 
-FAQ
----
-
-**Q1**: What is the difference between the mini and medium versions of MatterSim?
-
-   **A**: The mini version is a smaller model that is faster to run, while the medium version is more accurate.
-
-**Q2**: Are you going to release the pre-trained models of MatterSim with transformer-based architectures?
-
-   **A**: The transformer-based MatterSim is still under development. Please contact us for more information.
-
 Bibliography
 ------------
 
@@ -51,20 +40,36 @@ Bibliography
    .. code-block:: bibtex
 
       @article{yang2024mattersim,
-         title={
-            Mattersim: A deep learning atomistic model across elements,
-            temperatures and pressures
-         },
-         author={
-            Yang, Han and Hu, Chenxi and Zhou, Yichi and Liu, Xixian
-            and Shi, Yu and Li, Jielan and Li, Guanzhi and Chen, Zekun
-            and Chen, Shuizhou and Zeni, Claudio and others
-         },
-         journal={arXiv preprint arXiv:2405.04967},
-         year={2024}
+         title={MatterSim: A Deep Learning Atomistic Model Across Elements, Temperatures and Pressures}, 
+         author={Han Yang and Chenxi Hu and Yichi Zhou and Xixian Liu and Yu Shi and Jielan Li and Guanzhi Li and Zekun Chen and Shuizhou Chen and Claudio Zeni and Matthew Horton and Robert Pinsler and Andrew Fowler and Daniel Zügner and Tian Xie and Jake Smith and Lixin Sun and Qian Wang and Lingyu Kong and Chang Liu and Hongxia Hao and Ziheng Lu},
+         year={2024},
+         eprint={2405.04967},
+         archivePrefix={arXiv},
+         primaryClass={cond-mat.mtrl-sci},
+         url={https://arxiv.org/abs/2405.04967},
+         journal={arXiv preprint arXiv:2405.04967
       }
 
 
+Frequently Asked Questions
+--------------------------
+
+**Q1**: I have identified a system where MatterSim produces inaccurate or unexpected results. How can I report this?
+
+   **A**: We welcome and appreciate detailed bug reports to help improve MatterSim. Please raise an issue on our GitHub repository: https://github.com/microsoft/mattersim/issues.
+
+**Q2**: I have specific need for some features that are not currently supported by MatterSim. How can I request these features?
+
+   **A**: We are always looking to improve MatterSim and welcome feature requests. Please suggest a feature on our GitHub repository: https://github.com/microsoft/mattersim/issues.
+
+**Q3**: Do you have any plans to release more pre-trained models in the future?
+
+   **A**: Yes, we are actively working on developing more pre-trained models for MatterSim. Please stay tuned for updates.
+
+**Q4**: How can I contribute to the development of MatterSim?
+
+   **A**: We warmly welcome contributions! Please help improve MatterSim by reporting bugs, suggesting features, or submitting pull requests to our GitHub repository: https://github.com/microsoft/mattersim/pulls.
+
 
 .. toctree::
    :maxdepth: 2