Contributing to Emper Labs
Thank you for your interest in contributing to Emper Labs!
Emper Labs is an open-source project focused on building an ecosystem for scientific simulation, high-performance computing, and research. We welcome valuable contributions from anyone in the community.
🤝 Who Can Contribute?
Everyone is welcome.
You do not need to be an expert. We welcome contributions from:
- Software developers
- Scientists and researchers
- Simulation and computational engineers
- AI/ML researchers
- Students
- Beginners
- Anyone interested in scientific simulation
What matters most is not your title or experience level, but the quality of your contribution, willingness to learn, and responsibility for the changes you submit.
📋 Ways to Contribute
- Code
You can contribute by:
- Fixing bugs
- Adding features
- Improving performance
- Building new modules
- Improving APIs
- Writing unit tests
- Improving backends or compute pipelines
- Optimizing memory usage or data layouts
- Documentation
You can help improve:
- README files
- API documentation
- Tutorials
- Examples
- Technical documentation
- Code comments
- Translations
Technical articles and tutorial videos are also welcome.
- Testing & Bug Reports
You can help by:
- Finding and reporting bugs
- Testing on different hardware or operating systems
- Writing regression tests
- Writing benchmarks
- Testing edge cases
A good bug report should include:
- A description of the problem
- Steps to reproduce
- Expected behavior
- Actual behavior
- Relevant environment information
- Logs or screenshots when appropriate
- Architecture & Research
Emper Labs is not just a software project.
Contributions related to:
- Engine architecture
- Simulation algorithms
- Numerical methods
- Data-oriented design
- Parallel computing
- GPU computing
- Physics
- Biology
- Chemistry
- AI/ML
- Other scientific disciplines
are welcome.
For major changes, please open a discussion or issue before implementation so the overall direction can be agreed upon.
🤖 AI Usage Policy
Emper Labs allows and welcomes the use of AI tools such as GitHub Copilot, ChatGPT, Claude, and similar tools.
AI can be a useful tool for accelerating development. However:
«Contributors are fully responsible for the final code they submit, regardless of whether it was written manually or generated with AI assistance.»
✅ Allowed
AI may be used for:
- Boilerplate code
- Scaffolding
- Implementation suggestions
- Debugging assistance
- Optimization suggestions
- Documentation
- Comments
- Code translation
- Code or algorithm explanations
- Technical research and exploration
AI-generated or AI-assisted code must be read, understood, and reviewed by the contributor before being submitted.
Contributors must ensure:
Correctness
- The code behaves as intended.
- Relevant tests pass.
- No regressions are introduced.
- Important logic has been appropriately verified.
Technical Alignment
Code must:
- Follow Emper's architecture.
- Follow the project's coding style.
- Use existing APIs and abstractions appropriately.
- Avoid unnecessary dependencies.
- Not violate existing design decisions without prior discussion.
Performance
For changes that affect performance, contributors should:
- Run appropriate benchmarks.
- Compare against the previous implementation when possible.
- Report the performance impact.
- Explain significant regressions when they occur.
Not every PR requires a benchmark. Documentation changes, typo fixes, metadata changes, and other changes with no meaningful performance impact do not require one.
❌ Not Accepted
Do not submit a PR if:
- You do not understand the code you are submitting.
- AI-generated code has not been properly reviewed.
- You expect maintainers to verify the code for you.
- AI-generated code was introduced without considering its architectural or performance impact.
AI is a development tool, not the person responsible for the PR.
🔀 Pull Request Guidelines
Before opening a Pull Request:
- Create a dedicated branch in your fork for your changes.
- Keep the scope focused.
- Make sure the project builds successfully.
- Run relevant tests.
- Run benchmarks when the change affects performance.
- Review your changes before submitting the PR.
A PR should explain:
- What — What did you change?
- Why — Why is the change needed?
- How — How did you implement it?
- Testing — What did you test?
- Benchmark — If performance-related, what were the results?
- Breaking Changes — Are there any breaking changes?
A small, focused, easy-to-review PR is generally better than a large PR containing unrelated changes.
🧪 Testing
Changes should be tested at a level appropriate to their scope.
For example:
- Bug fix → add a regression test when appropriate.
- API change → verify affected callers.
- Performance optimization → run benchmarks.
- GPU code → verify synchronization, memory access, and correctness.
- Simulation algorithm → verify simulation results.
- Documentation → verify formatting and accuracy.
📊 Performance Contributions
Emper Labs places a strong emphasis on performance.
When optimizing a part of the engine, try to provide:
- Hardware
- Compiler/toolchain
- Build configuration
- Dataset or simulation size
- Baseline
- New result
- Benchmark methodology
For example:
Hardware: AMD Radeon RX 580 Simulation: 100,000 particles Baseline: 42 FPS New: 57 FPS Improvement: +35.7%
Benchmarks do not need to be perfect, but they should be reproducible and honest.
🧠 Large Changes
For major changes such as:
- Architecture changes
- API redesigns
- New subsystems
- Changes to the storage model
- Changes to compute backends
- Changes to simulation models
please open an issue or discussion before implementation.
This helps avoid contributors spending significant time building an implementation that does not fit the project's direction.
📜 Code of Conduct
Please treat other contributors with respect and professionalism.
Technical disagreement is completely normal and encouraged. However, discussions should focus on ideas, implementations, and technical reasoning, not individuals.
❤️ Thank You for Contributing!
Every bug report, benchmark, documentation improvement, experiment, and pull request can help move Emper Labs forward.
Build. Simulate. Discover.