How to Report a Bug
We use GitHub Issues to track bugs, feature requests, and questions. Reporting issues through GitHub ensures they are visible to the entire community and can be addressed systematically by the development team.
Before opening a new issue, search the existing issues to check if your problem has already been reported. This helps avoid duplicates and may lead you to a solution faster.
Steps to Submit an Issue
- Go to the MAPLE Issues page on GitHub.
- Click "New issue" to create a new report.
- Choose the appropriate issue type (Bug report, Feature request, or Question).
- Fill in the template with as much detail as possible.
- Submit the issue.
What to Include in a Bug Report
A good bug report helps us reproduce and fix the problem quickly. Please include the following information:
- MAPLE version — Run
python -c "import maple; print(maple.__version__)"to find your version. - Python version — Run
python --version. - Operating system — e.g., Ubuntu 22.04, CentOS 8, macOS 14.
- GPU and CUDA version — Run
nvidia-smito check. - Input file — The
.inpfile (or a minimal reproduction) that triggers the issue. - Full error message — Copy the complete traceback or error output.
- Expected behavior — What you expected to happen.
- Actual behavior — What actually happened.
Example Bug Report
Title: Optimization crashes with MACE-OFF23 on molecules with fluorine
Description:
Running geometry optimization with maceoff23s on a fluorine-containing
molecule causes a RuntimeError during force evaluation.
MAPLE version: 2025.3
Python: 3.11.5
OS: Ubuntu 22.04
GPU: NVIDIA A100, CUDA 12.1
Input file:
#model=maceoff23s
#opt(method=lbfgs)
#device=gpu0
C 0.000 0.000 0.000
F 1.350 0.000 0.000
Error:
RuntimeError: element index out of range in model forward passFor general questions about how to use MAPLE, consider checking the Documentation first. Many common questions are answered in the tutorials and reference pages.
Feature Requests
We welcome suggestions for new features and improvements. When submitting a feature request, please describe:
- The problem you are trying to solve or the workflow you want to improve.
- Your proposed solution or the behavior you would like to see.
- Any alternatives you have considered.
Contact
For issues that cannot be reported through GitHub (e.g., security vulnerabilities), please contact the development team directly through the repository contact information.