Report an Issue

Help us improve MAPLE by reporting bugs, requesting features, or asking questions.

We welcome feedback from the MAPLE community! If you encounter a bug, have a feature request, or need help, please report it on our GitHub repository. This ensures that all issues are tracked, visible to other users, and can be addressed efficiently by the development team.

Open an issue on GitHub →

How to Report an Issue on GitHub

Follow these step-by-step instructions to create a clear and helpful issue report:

Step 1: Navigate to the Issues Page

  1. Visit the MAPLE GitHub repository.
  2. Click on the "Issues" tab at the top of the repository page.
  3. Click the green "New Issue" button.

Step 2: Fill in the Issue Title

Write a clear, concise title that summarizes the problem or request. Good titles are specific and descriptive.

Examples:
✓ "Segmentation fault during optimization with ANI-2x model"
✓ "Add support for XYZ file format in batch processing"
✗ "MAPLE doesn't work"
✗ "Help needed"

Step 3: Provide Detailed Information

Include the following information to help us understand and reproduce your issue:

For Bug Reports:

  • Description: Clear explanation of what happened versus what you expected.
  • Steps to Reproduce:
    1. Step-by-step instructions to reproduce the bug
    2. Include input file contents or commands used
  • Environment:
    • Operating System (e.g., Linux Ubuntu 22.04, Windows 11, macOS 14)
    • Python version (if applicable)
    • MAPLE version
    • Hardware (CPU/GPU model if relevant)
  • Error Messages: Copy and paste the full error message or stack trace
  • Input Files: Attach or paste relevant input files (.inp files, coordinates, etc.)
  • Output Files: If applicable, attach relevant output files or logs

For Feature Requests:

  • Problem Statement: Describe the limitation or missing functionality
  • Proposed Solution: Explain how you envision the feature working
  • Use Case: Provide examples of how this feature would be useful
  • Alternatives: Describe any workarounds you're currently using

For Questions:

  • Question: Clearly state what you want to know
  • Context: Provide relevant details about your use case
  • What You've Tried: Describe any attempts you've made to find the answer

Step 4: Format Your Issue

GitHub supports Markdown formatting. Use it to make your issue readable:

  • Use `code` for inline code or file names
  • Use ```language blocks for code snippets
  • Use **bold** for emphasis
  • Use numbered lists for steps and bullet points for items
  • Use headings to organize sections

Example formatted code block:

```python
#model=ani2x
#opt(method=lbfgs)
#device=cuda

Best Practices for Issue Reporting

  • Search first: Check if a similar issue already exists before creating a new one. You can add your information as a comment to an existing issue.
  • Be specific: Provide exact error messages, version numbers, and step-by-step reproduction instructions.
  • Minimize examples: If possible, reduce your input to the smallest case that still reproduces the issue.
  • Be respectful: Remember that developers are volunteers or working within limited resources. Polite, constructive feedback is always appreciated.
  • Update issues: If you find a solution or the issue is resolved, let us know!
  • One issue per report: Create separate issues for different problems to keep discussions focused.

Issue Templates Example

Here's an example of a well-formatted bug report:

Description
MAPLE crashes with segmentation fault when running optimization with ANI-2x model on GPU.

Steps to Reproduce
1. Create input file with #model=ani2x, #opt(method=lbfgs), #device=gpu0
2. Run MAPLE with the input file
3. Segmentation fault occurs after 15 iterations

Expected Behavior
Optimization should complete successfully.

Environment
- OS: Ubuntu 22.04 LTS
- Python: 3.10.12
- MAPLE version: 2025.1
- GPU: NVIDIA RTX 3090, CUDA 11.8
- Driver version: 525.105.17

Error Message
Segmentation fault (core dumped)

Input File
[Attach or paste input file here]